docs(config): v3 스키마 재편 설계 + 구현 계획

Merge pull request 'feat(ocr): PP-OCRv5 ONNX Rust 네이티브 OCR 엔진' (#206 ) from feat/rust-native-ocr into main
Reviewed-on: #206
2026-06-04 12:25:49 +00:00 · 2026-06-04 09:24:37 +00:00 · 2026-06-04 09:13:27 +00:00 · 2026-06-04 08:36:34 +00:00 · 2026-06-04 08:36:19 +00:00 · 2026-06-04 08:22:47 +00:00
31 changed files with 16621 additions and 79 deletions
--- a/.gitattributes
+++ b/.gitattributes
@@ -0,0 +1,6 @@
+# PP-OCRv5 ONNX OCR models (paddle-onnx engine). git-lfs is not installed on
+# this host, so they are committed as plain binary blobs (treated as binary —
+# no textual diff/merge). If/when git-lfs becomes available, migrate with
+# `git lfs migrate import --include='*.onnx'` and restore the filter line:
+#   *.onnx filter=lfs diff=lfs merge=lfs -text
+*.onnx -text
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -4417,6 +4417,24 @@ dependencies = [
 "quick-error 2.0.1",
 ]

+[[package]]
+name = "imageproc"
+version = "0.25.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "602b4e8a4cc3e98372b766cd184ab532999bc0e839b7469e759511ccabc65d77"
+dependencies = [
+ "ab_glyph",
+ "approx",
+ "getrandom 0.2.17",
+ "image",
+ "itertools 0.12.1",
+ "nalgebra",
+ "num",
+ "rand 0.8.6",
+ "rand_distr 0.4.3",
+ "rayon",
+]
+
 [[package]]
 name = "imgref"
 version = "1.12.1"
@@ -4548,6 +4566,15 @@ dependencies = [
 "either",
 ]

+[[package]]
+name = "itertools"
+version = "0.12.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ba291022dbbd398a455acf126c1e341954079855bc60dfdda641363bd6922569"
+dependencies = [
+ "either",
+]
+
 [[package]]
 name = "itertools"
 version = "0.13.0"
@@ -4724,7 +4751,7 @@ dependencies = [

 [[package]]
 name = "kebab-app"
-version = "0.26.1"
+version = "0.27.0"
 dependencies = [
 "anyhow",
 "base64 0.22.1",
@@ -4772,7 +4799,7 @@ dependencies = [

 [[package]]
 name = "kebab-chunk"
-version = "0.26.1"
+version = "0.27.0"
 dependencies = [
 "anyhow",
 "blake3",
@@ -4790,7 +4817,7 @@ dependencies = [

 [[package]]
 name = "kebab-cli"
-version = "0.26.1"
+version = "0.27.0"
 dependencies = [
 "anyhow",
 "clap",
@@ -4811,7 +4838,7 @@ dependencies = [

 [[package]]
 name = "kebab-config"
-version = "0.26.1"
+version = "0.27.0"
 dependencies = [
 "anyhow",
 "dirs 5.0.1",
@@ -4827,7 +4854,7 @@ dependencies = [

 [[package]]
 name = "kebab-core"
-version = "0.26.1"
+version = "0.27.0"
 dependencies = [
 "anyhow",
 "blake3",
@@ -4841,7 +4868,7 @@ dependencies = [

 [[package]]
 name = "kebab-embed"
-version = "0.26.1"
+version = "0.27.0"
 dependencies = [
 "anyhow",
 "blake3",
@@ -4855,7 +4882,7 @@ dependencies = [

 [[package]]
 name = "kebab-embed-candle"
-version = "0.26.1"
+version = "0.27.0"
 dependencies = [
 "anyhow",
 "candle-core",
@@ -4875,7 +4902,7 @@ dependencies = [

 [[package]]
 name = "kebab-embed-local"
-version = "0.26.1"
+version = "0.27.0"
 dependencies = [
 "anyhow",
 "fastembed",
@@ -4888,7 +4915,7 @@ dependencies = [

 [[package]]
 name = "kebab-embed-ollama"
-version = "0.26.1"
+version = "0.27.0"
 dependencies = [
 "anyhow",
 "kebab-config",
@@ -4903,7 +4930,7 @@ dependencies = [

 [[package]]
 name = "kebab-eval"
-version = "0.26.1"
+version = "0.27.0"
 dependencies = [
 "anyhow",
 "kebab-app",
@@ -4922,7 +4949,7 @@ dependencies = [

 [[package]]
 name = "kebab-llm"
-version = "0.26.1"
+version = "0.27.0"
 dependencies = [
 "anyhow",
 "kebab-core",
@@ -4931,7 +4958,7 @@ dependencies = [

 [[package]]
 name = "kebab-llm-local"
-version = "0.26.1"
+version = "0.27.0"
 dependencies = [
 "anyhow",
 "kebab-config",
@@ -4948,7 +4975,7 @@ dependencies = [

 [[package]]
 name = "kebab-mcp"
-version = "0.26.1"
+version = "0.27.0"
 dependencies = [
 "anyhow",
 "kebab-app",
@@ -4966,7 +4993,7 @@ dependencies = [

 [[package]]
 name = "kebab-nli"
-version = "0.26.1"
+version = "0.27.0"
 dependencies = [
 "anyhow",
 "hf-hub",
@@ -4981,7 +5008,7 @@ dependencies = [

 [[package]]
 name = "kebab-parse-code"
-version = "0.26.1"
+version = "0.27.0"
 dependencies = [
 "anyhow",
 "gix",
@@ -5004,22 +5031,26 @@ dependencies = [

 [[package]]
 name = "kebab-parse-image"
-version = "0.26.1"
+version = "0.27.0"
 dependencies = [
 "ab_glyph",
 "anyhow",
 "base64 0.22.1",
 "blake3",
 "image",
+ "imageproc",
 "kamadak-exif",
 "kebab-config",
 "kebab-core",
 "kebab-llm",
 "kebab-llm-local",
+ "ndarray",
+ "ort",
 "reqwest 0.12.28",
 "serde",
 "serde_json",
 "tempfile",
+ "thiserror 2.0.18",
 "time",
 "tokio",
 "tracing",
@@ -5028,7 +5059,7 @@ dependencies = [

 [[package]]
 name = "kebab-parse-md"
-version = "0.26.1"
+version = "0.27.0"
 dependencies = [
 "anyhow",
 "kebab-core",
@@ -5045,7 +5076,7 @@ dependencies = [

 [[package]]
 name = "kebab-parse-pdf"
-version = "0.26.1"
+version = "0.27.0"
 dependencies = [
 "anyhow",
 "blake3",
@@ -5060,7 +5091,7 @@ dependencies = [

 [[package]]
 name = "kebab-rag"
-version = "0.26.1"
+version = "0.27.0"
 dependencies = [
 "anyhow",
 "blake3",
@@ -5082,7 +5113,7 @@ dependencies = [

 [[package]]
 name = "kebab-search"
-version = "0.26.1"
+version = "0.27.0"
 dependencies = [
 "anyhow",
 "globset",
@@ -5101,7 +5132,7 @@ dependencies = [

 [[package]]
 name = "kebab-source-fs"
-version = "0.26.1"
+version = "0.27.0"
 dependencies = [
 "anyhow",
 "blake3",
@@ -5119,7 +5150,7 @@ dependencies = [

 [[package]]
 name = "kebab-store-sqlite"
-version = "0.26.1"
+version = "0.27.0"
 dependencies = [
 "anyhow",
 "blake3",
@@ -5139,7 +5170,7 @@ dependencies = [

 [[package]]
 name = "kebab-store-vector"
-version = "0.26.1"
+version = "0.27.0"
 dependencies = [
 "anyhow",
 "arrow",
@@ -5163,7 +5194,7 @@ dependencies = [

 [[package]]
 name = "kebab-tui"
-version = "0.26.1"
+version = "0.27.0"
 dependencies = [
 "anyhow",
 "crossterm",
@@ -6423,6 +6454,21 @@ version = "0.1.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "13d2233c9842d08cfe13f9eac96e207ca6a2ea10b80259ebe8ad0268be27d2af"

+[[package]]
+name = "nalgebra"
+version = "0.32.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7b5c17de023a86f59ed79891b2e5d5a94c705dbe904a5b5c9c952ea6221b03e4"
+dependencies = [
+ "approx",
+ "matrixmultiply",
+ "num-complex",
+ "num-rational",
+ "num-traits",
+ "simba",
+ "typenum",
+]
+
 [[package]]
 name = "native-tls"
 version = "0.2.18"
@@ -8238,6 +8284,15 @@ version = "1.0.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "dd29631678d6fb0903b69223673e122c32e9ae559d0960a38d574695ebc0ea15"

+[[package]]
+name = "safe_arch"
+version = "0.7.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "96b02de82ddbe1b636e6170c21be622223aea188ef2e139be0a5b219ec215323"
+dependencies = [
+ "bytemuck",
+]
+
 [[package]]
 name = "safetensors"
 version = "0.4.5"
@@ -8615,6 +8670,19 @@ dependencies = [
 "libc",
 ]

+[[package]]
+name = "simba"
+version = "0.8.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "061507c94fc6ab4ba1c9a0305018408e312e17c041eb63bef8aa726fa33aceae"
+dependencies = [
+ "approx",
+ "num-complex",
+ "num-traits",
+ "paste",
+ "wide",
+]
+
 [[package]]
 name = "simd-adler32"
 version = "0.3.9"
@@ -10220,6 +10288,16 @@ version = "0.1.12"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a28ac98ddc8b9274cb41bb4d9d4d5c425b6020c50c46f25559911905610b4a88"

+[[package]]
+name = "wide"
+version = "0.7.33"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0ce5da8ecb62bcd8ec8b7ea19f69a51275e91299be594ea5cc6ef7819e16cd03"
+dependencies = [
+ "bytemuck",
+ "safe_arch",
+]
+
 [[package]]
 name = "winapi"
 version = "0.3.9"
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -32,7 +32,7 @@ edition       = "2024"
 rust-version  = "1.85"
 license       = "MIT OR Apache-2.0"
 repository    = "https://github.com/altair823/kebab"
-version       = "0.26.1"   # v0.26.1 — ingest 진행 로그 개선: TTY 진행바에 현재 파일명 + 느린 phase(ocr/caption/embed)+모델명 실시간 + 경과초 heartbeat `(Ns)`, 종료 시 최장 소요 파일 top-5 요약. 신규 wire 이벤트 `asset_phase{idx,total,phase,model}` + `asset_timings.ocr_ms`/`caption_ms` 추가(additive, ingest_progress.v1 유지, serde default 0). 기본 동작 불변. — CLAUDE.md §Release
+version       = "0.27.0"   # v0.27.0 — PP-OCRv5 ONNX Rust 네이티브 OCR 엔진: `[image.ocr] engine = "paddle-onnx"` (default 여전히 "ollama-vision") 로 in-process 검출+인식(`ort` =2.0.0-rc.9, Python 런타임 0). DBNet det + CTC rec, 후처리(min-area rect/unclip)는 pure-Rust. e2e CER 0.005(synthetic 한/영, PoC 0.024 대비 우수), 큰 페이지 CPU <4초(Ollama vision ~50초 대비). 신규 config `det_model`/`rec_model`/`dict`/`score_thresh`/`unclip_ratio`/`max_boxes` + `KEBAB_IMAGE_OCR_*` env. ingest 서명 `|ocr:1:{engine}:{engine_version}` 로 engine/모델 변경 시 자동 재색인. 신규 인터페이스(engine 값/config 키) → minor. — CLAUDE.md §Release

 # pre-v0.18 workspace-wide cleanup: enable clippy::pedantic group with
 # intentional allow-list. The allowed lints are either cosmetic (doc style),
--- a/HANDOFF.md
+++ b/HANDOFF.md
@@ -35,6 +35,8 @@ P0~P5 직렬. P6~P9 P5 이후 병렬 가능.

 머지 후 발견된 모든 deviation / hotfix 의 dated 로그는 [tasks/HOTFIXES.md](tasks/HOTFIXES.md). 본 요약은 \"누군가가 인수받을 때 알아두면 시간을 많이 절약하는\" 항목만:

+- **2026-06-04 PP-OCRv5 ONNX Rust 네이티브 OCR** — v0.27.0. `[image.ocr] engine = "paddle-onnx"` 로 PP-OCRv5(검출+인식) ONNX 를 in-process(`ort` =2.0.0-rc.9) 실행 — Python 런타임/원격 호출 없이 큰 페이지 CPU <4초(Ollama vision ~50초 대비). default 는 여전히 `"ollama-vision"`. 후처리(min-area rect/unclip)는 pure-Rust. **함정**: unclip 은 corner 를 centroid 에서 방사 확장하면 안 되고 edge 별 polygon offset 이어야 함(방사 확장 시 wide/short 텍스트 박스 높이가 안 커져 글자 윗부분 잘림 → ㄷ→ㄴ, e2e CER 0.26). 수정 후 CER 0.005. 모델 ONNX 는 `crates/kebab-parse-image/assets/paddleocr-onnx/`(LFS). 자세한 내용: `tasks/HOTFIXES.md` (2026-06-04 PP-OCRv5 ONNX), spec/plan `docs/superpowers/{specs,plans}/2026-06-04-rust-native-ocr-*.md`.
+- **2026-06-03 ingest 설정 변경 자동 재색인** — v0.26.2. ingest 산출에 영향 주는 설정(청킹/이미지 OCR·caption/pdf.ocr/`[ingest.code]`)을 변경하면 `--force-reingest` 없이 영향 자산만 자동 재색인. 그 설정들의 결정적 서명(`ingest_config_signature`)을 effective parser_version(skip 비교 + 저장 doc 필드 양쪽)에 폴딩 → 다음 ingest 비교가 mismatch. 비산출 설정(search/rag/ui/log + max_pixels/languages/timeout)은 제외(과도 무효화 회피), doc_id 는 base 로 안정 유지. **업그레이드 후 첫 ingest 는 전 자산 1회 재색인**(저장된 상수 parser_version ≠ 새 composite; embedding 은 V012 캐시 히트). 결과 포맷·CLI·wire 불변(내부 skip 판정 정정). 자세한 내용: `tasks/HOTFIXES.md` (2026-06-03 ingest 설정 변경 자동 재색인), spec/plan `docs/superpowers/{specs,plans}/2026-06-03-*invalidation*.md`.
 - **2026-06-03 ingest 진행 로그 개선** — v0.26.1. 이미지/PDF + OCR/caption on 볼트 ingest 가 "멈춘 듯" 보이던 문제 해소: TTY 진행바에 현재 파일명 + 느린 phase(ocr/caption/embed)+모델명 + 경과초 `(Ns)` heartbeat, 종료 시 최장 소요 파일 top-5 요약. 신규 wire `asset_phase{idx,total,phase,model}` + `asset_timings.ocr_ms`/`caption_ms`(additive, `ingest_progress.v1` 유지, serde default 0). 이미지·PDF 경로도 `asset_timings` emit(이전 markdown 만). 기본 동작 불변. 자세한 내용: `tasks/HOTFIXES.md` (2026-06-03 ingest 진행 로그), spec/plan `docs/superpowers/{specs,plans}/2026-06-03-ingest-log-improve-*.md`.
 - **2026-06-03 arctic-embed-l-v2.0 임베더 통합** — v0.26.0. 별칭 제거 후 설명형 query recall 보강(측정 recall@10 130/132, e5 +7). `kebab-embed-candle` 모델 레지스트리화(e5 mean + `snowflake-arctic-embed-l-v2.0` CLS, 모델별 pooling/prefix) + 신규 `kebab-embed-ollama`(`provider="ollama"`, `/api/embed`). config `endpoint: Option<String>` 추가. 기본 e5 유지(opt-in), arctic 전환은 embedding_version cascade → 재색인. candle↔Ollama cosine>0.99 게이트로 pooling/prefix 정확성 고정(`#[ignore]`). 자세한 내용: `tasks/HOTFIXES.md` (2026-06-03 arctic), spec `docs/superpowers/specs/2026-06-03-arctic-embedder-spec.md`.
 - **2026-06-03 doc-side expansion(별칭) 기능 완전 제거** — v0.25.0. 아래 2026-05-31 항목의 색인-시 청크당 LLM 별칭 생성 + 별칭 검색 채널을 **전부 제거**(ROI 음수: cross-lingual 은 e5-large 단독으로 충분, 기여는 설명형 +2 그룹뿐인데 대가가 청크당 색인-시 LLM). `Chunk.aliases`/`expansion.rs`/`IngestExpansionCfg`/alias lexical arm/`expansion_progress` wire kind 제거, 신규 마이그레이션 **V013** 이 `chunk_aliases_fts`+`chunks.aliases` DROP. 별칭 default-off 였어 사용자 체감 0, 기존 KB 도 재색인 불요(잔존 별칭 벡터는 `strip_alias_suffix` graceful 매핑/`reset` 정리). `AssetTimings.expansion_ms` 는 wire 호환 위해 값 0 으로 유지. 자세한 내용: `tasks/HOTFIXES.md` (2026-06-03), spec `docs/superpowers/specs/2026-06-03-remove-doc-expansion-spec.md`.
--- a/README.md
+++ b/README.md
@@ -184,7 +184,8 @@ nli_threshold = 0.0                  # >0 (예: 0.5) 면 mDeBERTa XNLI groundedn

 - **파생물 캐시** — embedding 결과를 내용 해시로 자동 캐싱한다 (위 「핵심 기능」 참고). 설정 항목 없음.
 - **`[ingest.code]`** — code ingest 의 skip 정책 (`skip_generated_header`, `max_file_bytes`, `extra_skip_globs`). `.gitignore` 자동 honor, `.kebabignore` 는 추가 layer.
- **`[pdf.ocr]`** — scanned PDF 의 page-단위 OCR (default off / opt-in, page 당 ~수십 초 cost). 활성화 후 v0.19 시절 색인분은 `kebab ingest --force-reingest` 로 재처리.
+- **`[image.ocr]`** — 이미지 OCR (default off / opt-in). `engine` 으로 백엔드 선택: `"ollama-vision"` (default, 원격 vision LM) 또는 `"paddle-onnx"` (v0.27.0 신규 — PP-OCRv5 ONNX 를 in-process 로 실행, Python 런타임 불필요, 큰 페이지 CPU <4초, 오프라인). `paddle-onnx` 는 워크스페이스에 번들된 모델을 쓰며 `det_model`/`rec_model`/`dict` 로 경로 override, `score_thresh`(0.3)/`unclip_ratio`(1.5)/`max_boxes`(1000) 로 검출 튜닝 가능 (`KEBAB_IMAGE_OCR_*` env 동일 지원). engine 또는 모델을 바꾸면 영향 이미지가 자동 재색인된다.
+- **`[pdf.ocr]`** — scanned PDF 의 page-단위 OCR (default off / opt-in, page 당 ~수십 초 cost). `engine` 은 `[image.ocr]` 과 동일하게 `"ollama-vision"`/`"paddle-onnx"` 선택. 활성화 후 v0.19 시절 색인분은 `kebab ingest --force-reingest` 로 재처리.
 - **`--config <path>`** — 임시 워크스페이스 / 격리 테스트용 (CLI · TUI 모두 honor).
 - **`kebab config migrate`** — 새 버전에서 추가된 config 섹션을 기존 `config.toml` 에 설명 주석과 함께 채워 넣는다 (사용자가 손본 값·주석·순서는 보존, 멱등, 변경 시 자동 `.bak` 백업). `--dry-run` 으로 변경 미리보기. `kebab doctor` 가 갱신 필요 시 안내한다. `kebab init` 으로 새로 생성되는 config.toml 도 섹션별 주석을 포함한다.
 - **`KEBAB_*` env** — 일부 키 override (`KEBAB_RAG_SCORE_GATE`, `KEBAB_EVAL_GOLDEN` 등).
--- a/crates/kebab-app/src/lib.rs
+++ b/crates/kebab-app/src/lib.rs
@@ -52,7 +52,10 @@ use kebab_core::{
    SearchHit, SearchQuery, SourceScope, SourceUri, VectorRecord, VectorStore,
 };
 use kebab_llm_local::OllamaLanguageModel;
-use kebab_parse_image::{OcrEngine, OllamaVisionOcr, apply_caption, apply_ocr};
+use kebab_parse_image::{
+    OLLAMA_VISION_ENGINE, OcrEngine, OllamaVisionOcr, OnnxPaddleOcr, PADDLE_ONNX_ENGINE,
+    apply_caption, apply_ocr, engine_version_for_config,
+};
 use kebab_parse_md::{BodyHints, build_canonical_document, parse_blocks, parse_frontmatter};
 use kebab_source_fs::FsSourceConnector;

@@ -357,8 +360,8 @@ pub fn ingest_with_config_opts(
    // loop is correct and cheap. Construction failure (e.g. invalid
    // endpoint) aborts ingest fail-fast — better than silently disabling
    // OCR/caption mid-run.
-    let ocr_engine: Option<OllamaVisionOcr> = if app.config.image.ocr.enabled {
-        Some(OllamaVisionOcr::new(&app.config).context("kb-app::ingest: build OllamaVisionOcr")?)
+    let ocr_engine: Option<Box<dyn OcrEngine>> = if app.config.image.ocr.enabled {
+        Some(build_image_ocr_engine(&app.config).context("kb-app::ingest: build image OCR engine")?)
    } else {
        None
    };
@@ -370,28 +373,17 @@ pub fn ingest_with_config_opts(
        None
    };
    let image_pipeline = ImagePipeline {
-        ocr_engine: ocr_engine.as_ref(),
+        ocr_engine: ocr_engine.as_deref(),
        caption_llm: caption_llm.as_deref(),
    };

    // p10 / v0.20 sub-item 1: PDF OCR engine eager init (H-5 resolution).
    // image OCR pattern mirror — per-ingest 1회 build, fallible → fail-fast.
-    let pdf_ocr_engine: Option<OllamaVisionOcr> =
+    let pdf_ocr_engine: Option<Box<dyn OcrEngine>> =
        if app.config.pdf.ocr.enabled || app.config.pdf.ocr.always_on {
-            let cfg = &app.config.pdf.ocr;
-            let endpoint = match cfg.endpoint.as_deref() {
-                Some(s) if !s.is_empty() => s.to_string(),
-                _ => app.config.models.llm.endpoint.clone(),
-            };
            Some(
-                OllamaVisionOcr::from_parts(
-                    endpoint,
-                    cfg.model.clone(),
-                    cfg.languages.clone(),
-                    cfg.max_pixels,
-                    cfg.request_timeout_secs,
-                )
-                .context("kb-app::ingest: build OllamaVisionOcr (pdf)")?,
+                build_pdf_ocr_engine(&app.config)
+                    .context("kb-app::ingest: build pdf OCR engine")?,
            )
        } else {
            None
@@ -488,7 +480,7 @@ pub fn ingest_with_config_opts(
            &existing_doc_ids,
            &image_pipeline,
            force_reingest,
-            pdf_ocr_engine.as_ref(),
+            pdf_ocr_engine.as_deref(),
            progress,
            opts.cancel.as_ref(),
            log_writer.clone(),
@@ -832,11 +824,84 @@ fn mint_ingest_run_id(scope_json: &str, at: time::OffsetDateTime) -> String {
 /// `<… as JobRepo>` to be explicit.
 type SqliteStoreAlias = kebab_store_sqlite::SqliteStore;

+/// v0.27.0 (T8): build the image OCR engine selected by
+/// `config.image.ocr.engine`. Returns a boxed trait object so the ingest
+/// pipeline is engine-agnostic. Construction is fail-fast (model load /
+/// hash / endpoint validation) — mirrors the prior concrete-type behaviour.
+///
+/// `--config` facade: the caller threads the explicit [`kebab_config::Config`]
+/// in, so `OnnxPaddleOcr::new` honours `image.ocr.{det_model,rec_model,dict,…}`
+/// overrides resolved from that config (not a re-loaded XDG default).
+fn build_image_ocr_engine(
+    config: &kebab_config::Config,
+) -> anyhow::Result<Box<dyn OcrEngine>> {
+    match config.image.ocr.engine.as_str() {
+        OLLAMA_VISION_ENGINE => Ok(Box::new(
+            OllamaVisionOcr::new(config).context("build OllamaVisionOcr")?,
+        )),
+        PADDLE_ONNX_ENGINE => Ok(Box::new(
+            OnnxPaddleOcr::new(config).context("build OnnxPaddleOcr")?,
+        )),
+        other => anyhow::bail!(
+            "unknown image.ocr.engine {other:?}; expected \
+             {OLLAMA_VISION_ENGINE:?} or {PADDLE_ONNX_ENGINE:?}"
+        ),
+    }
+}
+
+/// v0.27.0 (T8): build the PDF OCR engine selected by
+/// `config.pdf.ocr.engine`. The ollama-vision arm uses the PDF-specific
+/// `model` / `languages` / `max_pixels` / `request_timeout_secs` knobs (and
+/// endpoint fallback to `models.llm.endpoint`). The paddle-onnx arm shares
+/// the same bundled ONNX models as image OCR (resolved from `image.ocr`
+/// overrides) — PaddleOCR is page-agnostic and carries no per-engine prompt.
+///
+/// # Paddle-ONNX asymmetry
+///
+/// When `pdf.ocr.engine = "paddle-onnx"`, the model paths and tuning knobs
+/// (`det_model`, `rec_model`, `dict`, `score_thresh`, `unclip_ratio`,
+/// `max_boxes`, `max_pixels`) are read from **`[image.ocr]`**, not
+/// `[pdf.ocr]`. PaddleOCR has no PDF-specific prompt or page-level config;
+/// `[pdf.ocr]` fields other than `engine` / `enabled` / `always_on` /
+/// `valid_ratio_threshold` / `min_char_count` / `lang_hint` are effectively
+/// ignored for the paddle path. This asymmetry is intentional — one set of
+/// tuned ONNX knobs serves both image and PDF pages.
+fn build_pdf_ocr_engine(
+    config: &kebab_config::Config,
+) -> anyhow::Result<Box<dyn OcrEngine>> {
+    match config.pdf.ocr.engine.as_str() {
+        OLLAMA_VISION_ENGINE => {
+            let cfg = &config.pdf.ocr;
+            let endpoint = match cfg.endpoint.as_deref() {
+                Some(s) if !s.is_empty() => s.to_string(),
+                _ => config.models.llm.endpoint.clone(),
+            };
+            Ok(Box::new(
+                OllamaVisionOcr::from_parts(
+                    endpoint,
+                    cfg.model.clone(),
+                    cfg.languages.clone(),
+                    cfg.max_pixels,
+                    cfg.request_timeout_secs,
+                )
+                .context("build OllamaVisionOcr (pdf)")?,
+            ))
+        }
+        PADDLE_ONNX_ENGINE => Ok(Box::new(
+            OnnxPaddleOcr::new(config).context("build OnnxPaddleOcr (pdf)")?,
+        )),
+        other => anyhow::bail!(
+            "unknown pdf.ocr.engine {other:?}; expected \
+             {OLLAMA_VISION_ENGINE:?} or {PADDLE_ONNX_ENGINE:?}"
+        ),
+    }
+}
+
 /// P6-4: borrowed bundle of the three image-pipeline components built
 /// once per ingest invocation. Threaded through `ingest_one_asset` so
 /// the dispatch does not need ten separate parameters.
 struct ImagePipeline<'a> {
-    ocr_engine: Option<&'a OllamaVisionOcr>,
+    ocr_engine: Option<&'a dyn OcrEngine>,
    caption_llm: Option<&'a dyn LanguageModel>,
 }

@@ -1110,7 +1175,7 @@ fn ingest_one_asset(
    existing_doc_ids: &std::collections::HashSet<String>,
    image_pipeline: &ImagePipeline<'_>,
    force_reingest: bool,
-    pdf_ocr_engine: Option<&OllamaVisionOcr>,
+    pdf_ocr_engine: Option<&dyn OcrEngine>,
    progress: Option<&std::sync::mpsc::Sender<crate::ingest_progress::IngestEvent>>,
    cancel: Option<&std::sync::Arc<std::sync::atomic::AtomicBool>>,
    log_writer: Option<Arc<Mutex<crate::ingest_log::IngestLogWriter>>>,
@@ -1242,6 +1307,12 @@ fn ingest_one_asset(
        }
    };

+    // v0.26.2: fold the ingest-config signature into the effective
+    // parser_version for the skip compare + the stored doc field, so a
+    // change to any markdown-affecting setting (chunking params) re-indexes.
+    // `doc_id` keeps deriving from the base version below (stability).
+    let eff_parser_version = effective_parser_version(&app.config, asset, parser_version);
+
    // p9-fb-23 task 7: incremental-ingest early-skip. When force_reingest
    // is false AND the on-disk asset's checksum + parser_version +
    // last_chunker_version + last_embedding_version all match the existing
@@ -1251,7 +1322,7 @@ fn ingest_one_asset(
    if let Some(item) = try_skip_unchanged(
        app,
        asset,
-        parser_version,
+        &eff_parser_version,
        &MdHeadingV1Chunker.chunker_version(),
        embedder.map(|e| e.model_version()).as_ref(),
        force_reingest,
@@ -1297,6 +1368,10 @@ fn ingest_one_asset(
    let mut canonical =
        build_canonical_document(asset, metadata, parsed_blocks, parser_version, all_warnings)
            .context("kb-parse-md::build_canonical_document")?;
+    // v0.26.2: persist the composite parser_version (base|signature) so the
+    // next run's skip compare matches what was computed above. doc_id was
+    // already derived from the base version inside build_canonical_document.
+    canonical.parser_version = eff_parser_version.clone();

    let parse_ms = u64::try_from(t_parse.elapsed().as_millis()).unwrap_or(u64::MAX);

@@ -1529,11 +1604,15 @@ fn ingest_one_image_asset(
    // embedding-version check matches the markdown path: when the
    // active embedder's model_version equals what was stamped on the
    // existing doc, the asset is Unchanged.
+    // v0.26.2: composite parser_version folds image OCR / caption + chunking
+    // settings, so toggling `[image.ocr]` / `[image.caption]` (or changing
+    // their model / prompt version) auto-re-indexes the affected images.
    let image_parser_version = ParserVersion(kebab_parse_image::PARSER_VERSION.to_string());
+    let eff_parser_version = effective_parser_version(&app.config, asset, &image_parser_version);
    if let Some(item) = try_skip_unchanged(
        app,
        asset,
-        &image_parser_version,
+        &eff_parser_version,
        &MdHeadingV1Chunker.chunker_version(),
        embedder.map(|e| e.model_version()).as_ref(),
        force_reingest,
@@ -1563,6 +1642,10 @@ fn ingest_one_image_asset(
    let mut canonical = app
        .extract_for(&asset.media_type, &ctx, &bytes)
        .context("kb-app::extract_for (image)")?;
+    // v0.26.2: store the composite parser_version (extractor baked the base
+    // `image-meta-v1`, which already fixed doc_id). Skip compare + stored
+    // field must agree for next-run detection.
+    canonical.parser_version = eff_parser_version.clone();
    let parse_ms = u64::try_from(t_parse.elapsed().as_millis()).unwrap_or(u64::MAX);

    // 2 + 3. Apply OCR / caption when their adapters exist. Both are
@@ -2075,7 +2158,7 @@ fn ingest_one_pdf_asset(
    vector_store: Option<&Arc<kebab_store_vector::LanceVectorStore>>,
    existing_doc_ids: &std::collections::HashSet<String>,
    force_reingest: bool,
-    pdf_ocr_engine: Option<&OllamaVisionOcr>,
+    pdf_ocr_engine: Option<&dyn OcrEngine>,
    progress: Option<&std::sync::mpsc::Sender<crate::ingest_progress::IngestEvent>>,
    cancel: Option<&std::sync::Arc<std::sync::atomic::AtomicBool>>,
    log_writer: Option<Arc<Mutex<crate::ingest_log::IngestLogWriter>>>,
@@ -2106,11 +2189,14 @@ fn ingest_one_pdf_asset(
    // p9-fb-23 task 7: incremental-ingest early-skip for the PDF flow.
    // PDF docs use `pdf-text-v1` as the parser_version and `PdfPageV1Chunker`
    // as the chunker — both pinned per-medium today (no config knob).
+    // v0.26.2: composite parser_version folds pdf.ocr (enabled/always_on/
+    // model) + chunking, so enabling scanned-PDF OCR auto-re-indexes PDFs.
    let pdf_parser_version = ParserVersion(kebab_parse_pdf::PARSER_VERSION.to_string());
+    let eff_parser_version = effective_parser_version(&app.config, asset, &pdf_parser_version);
    if let Some(item) = try_skip_unchanged(
        app,
        asset,
-        &pdf_parser_version,
+        &eff_parser_version,
        &PdfPageV1Chunker.chunker_version(),
        embedder.map(|e| e.model_version()).as_ref(),
        force_reingest,
@@ -2135,6 +2221,9 @@ fn ingest_one_pdf_asset(
    let mut canonical = app
        .extract_for(&asset.media_type, &ctx, &bytes)
        .context("kb-app::extract_for (pdf)")?;
+    // v0.26.2: store the composite parser_version (base `pdf-text-v1` already
+    // fixed doc_id) so the next run's skip compare matches.
+    canonical.parser_version = eff_parser_version.clone();
    let parse_ms = u64::try_from(t_parse.elapsed().as_millis()).unwrap_or(u64::MAX);

    // v0.20 sub-item 1: post-extract OCR enrichment (PR #187 registry
@@ -2510,10 +2599,19 @@ fn ingest_one_code_asset(
        _ => None,
    };

+    // v0.26.2: composite parser_version folds [ingest.code] options + common
+    // chunking so editing any code-ingest setting auto-re-indexes code assets.
+    // The base per-lang version still derives doc_id (synthesize_tier2_document
+    // / extract_for keep using `parser_version`). A Tier-3 fallback document
+    // intentionally keeps the bare "none-v1" parser_version (the
+    // `stored_is_tier3_fallback` bypass in try_skip_unchanged depends on the
+    // exact "none-v1" sentinel), so the composite is only stamped on the
+    // normal (non-fallback) outcome below.
+    let eff_parser_version = effective_parser_version(&app.config, asset, &parser_version);
    if let Some(item) = try_skip_unchanged(
        app,
        asset,
-        &parser_version,
+        &eff_parser_version,
        &chunker_version,
        embedder.map(|e| e.model_version()).as_ref(),
        force_reingest,
@@ -2678,6 +2776,20 @@ fn ingest_one_code_asset(
        }
    };

+    // v0.26.2: stamp the composite parser_version for the normal outcome so
+    // editing any [ingest.code] / chunking setting re-indexes this asset next
+    // run. A Tier-3 fallback (an AST / manifest lang whose extractor or
+    // chunker degraded to CodeTextParagraphV1Chunker) must keep the bare
+    // "none-v1" sentinel, because `try_skip_unchanged`'s
+    // `stored_is_tier3_fallback` bypass keys off that exact string. `shell`
+    // is native Tier 3 (no bypass — `tier3_fallback_cv` is None for it), so it
+    // still gets the composite.
+    let is_tier3_fallback_outcome =
+        code_lang != "shell" && chunker_version == CodeTextParagraphV1Chunker.chunker_version();
+    if !is_tier3_fallback_outcome {
+        canonical.parser_version = eff_parser_version.clone();
+    }
+
    // Stamp chunker + embedding versions so incremental skip detection has
    // data on the second run.
    canonical.last_chunker_version = Some(chunker_version.clone());
@@ -2951,6 +3063,158 @@ fn chunk_policy_from_config(config: &kebab_config::Config) -> ChunkPolicy {
    }
 }

+/// v0.26.2: deterministic signature of the **ingest-output-affecting**
+/// config for an asset's media type, folded into the effective
+/// `parser_version` (both the `try_skip_unchanged` compare field AND the
+/// persisted `documents.parser_version`). When any setting that changes the
+/// produced chunks / embeddings is edited, the next ingest's signature no
+/// longer matches the stored one → the affected assets (only) are
+/// automatically re-indexed without `--force-reingest`.
+///
+/// Inclusion rule: "does changing this value alter the chunk / embedding
+/// content that gets indexed?" Settings that do NOT (search / rag / nli /
+/// ui / logging / storage / workspace, plus runtime-only knobs like
+/// `max_pixels` / `languages` / `*_timeout_secs`) are deliberately excluded
+/// to avoid over-invalidation. Embedding model/dim is already covered by the
+/// separate `embedding_version` cascade in [`try_skip_unchanged`], so it is
+/// not duplicated here.
+///
+/// The output is purely a comparison token — it is never parsed back, so the
+/// exact format is internal. Field order is fixed and `Vec`s are joined so
+/// the same `Config` always yields the same string.
+/// Process-wide memo of the paddle-onnx `engine_version`, keyed by the
+/// resolved (det,rec,dict) override triple. Hashing the ~17 MB of model bytes
+/// happens once per triple per process (m3 — never re-hash per asset); the
+/// per-asset [`ingest_config_signature`] calls hit this cache.
+static PADDLE_OCR_VERSION_MEMO: std::sync::OnceLock<
+    std::sync::Mutex<std::collections::HashMap<String, String>>,
+> = std::sync::OnceLock::new();
+
+/// T9: resolve the OCR `engine_version` string used inside the ingest config
+/// signature. ollama-vision is self-describing from `engine/model` (cheap, no
+/// I/O). paddle-onnx hashes the bundled/override model assets (memoized).
+fn ocr_engine_version_for_sig(config: &kebab_config::Config, engine: &str, model: &str) -> String {
+    if engine != PADDLE_ONNX_ENGINE {
+        // ollama-vision (and any non-paddle engine): the daemon exposes no
+        // stable per-model revision, so engine/model is the identity.
+        return format!("ollama/{model}");
+    }
+    let ocr = &config.image.ocr;
+    let key = format!(
+        "{}|{}|{}",
+        ocr.det_model.as_deref().unwrap_or("<bundled>"),
+        ocr.rec_model.as_deref().unwrap_or("<bundled>"),
+        ocr.dict.as_deref().unwrap_or("<bundled>"),
+    );
+    let memo = PADDLE_OCR_VERSION_MEMO.get_or_init(|| std::sync::Mutex::new(std::collections::HashMap::new()));
+    if let Some(v) = memo.lock().unwrap().get(&key) {
+        return v.clone();
+    }
+    // First call for this triple in this process: hash once. In any real
+    // ingest the engine was already built (fail-fast) so the assets are
+    // present and this succeeds; the path-derived identity below is an
+    // unreachable-in-practice guard that keeps the signature total.
+    let version = engine_version_for_config(config).unwrap_or_else(|e| {
+        tracing::warn!(
+            target: "kebab-app::ingest",
+            error = %e,
+            "paddle-onnx engine_version hash failed; using path-derived identity for signature"
+        );
+        format!("ppocrv5-mobile-kor-paths:{key}")
+    });
+    memo.lock().unwrap().insert(key, version.clone());
+    version
+}
+
+fn ingest_config_signature(config: &kebab_config::Config, media: &MediaType) -> String {
+    // Common (every media type): chunking parameters that move chunk
+    // boundaries. `target_tokens` / `overlap_tokens` change re-chunking for
+    // markdown / image / pdf / code alike, so a change re-indexes all types.
+    let c = &config.chunking;
+    let mut sig = format!(
+        "chunk:{}:{}:{}:{}",
+        c.target_tokens, c.overlap_tokens, c.respect_markdown_headings, c.chunker_version
+    );
+    match media {
+        MediaType::Image(_) => {
+            // OCR / caption only affect output when their `enabled` flag is
+            // on; the model / prompt version matters only then. Off ↔ off is
+            // a stable empty token so re-running the same config skips.
+            let ocr = &config.image.ocr;
+            if ocr.enabled {
+                // v0.27.0 (T9): engine + engine_version so switching engine
+                // (ollama-vision ↔ paddle-onnx) OR changing the model/assets
+                // invalidates downstream chunks (design §9 cascade).
+                sig.push_str(&format!(
+                    "|ocr:1:{}:{}",
+                    ocr.engine,
+                    ocr_engine_version_for_sig(config, &ocr.engine, &ocr.model)
+                ));
+            } else {
+                sig.push_str("|ocr:0");
+            }
+            let cap = &config.image.caption;
+            if cap.enabled {
+                sig.push_str(&format!("|cap:1:{}", cap.prompt_template_version));
+            } else {
+                sig.push_str("|cap:0");
+            }
+        }
+        MediaType::Pdf => {
+            // PDF OCR is active when EITHER `enabled` or `always_on` is set
+            // (mirrors the ingest gate). `model` only matters when active.
+            let ocr = &config.pdf.ocr;
+            if ocr.enabled || ocr.always_on {
+                // v0.27.0 (T9): engine + engine_version (same cascade rule as
+                // image OCR above) alongside the enabled/always_on gate.
+                sig.push_str(&format!(
+                    "|pdfocr:{}:{}:{}:{}",
+                    ocr.enabled,
+                    ocr.always_on,
+                    ocr.engine,
+                    ocr_engine_version_for_sig(config, &ocr.engine, &ocr.model)
+                ));
+            } else {
+                sig.push_str("|pdfocr:0");
+            }
+        }
+        MediaType::Code(_) => {
+            let cc = &config.ingest.code;
+            sig.push_str(&format!(
+                "|code:{}:{}:{}:{}:{}:{}:{}",
+                cc.skip_generated_header,
+                cc.max_file_bytes,
+                cc.max_file_lines,
+                cc.extra_skip_globs.join(","),
+                cc.ast_chunk_max_lines,
+                cc.fallback_lines_per_chunk,
+                cc.fallback_lines_overlap
+            ));
+        }
+        // Markdown carries common-only; Audio / Other are not ingested yet.
+        MediaType::Markdown | MediaType::Audio(_) | MediaType::Other(_) => {}
+    }
+    sig
+}
+
+/// Compose an extractor's base `parser_version` with the ingest-config
+/// signature for `asset`'s media type. The result is used as the
+/// `try_skip_unchanged` compare value and stored on the persisted document,
+/// while the **base** version is what derives `doc_id` (kept stable to avoid
+/// orphan churn — see the spec at
+/// `docs/superpowers/specs/2026-06-03-ocr-toggle-invalidation-spec.md`).
+fn effective_parser_version(
+    config: &kebab_config::Config,
+    asset: &RawAsset,
+    base: &ParserVersion,
+) -> ParserVersion {
+    ParserVersion(format!(
+        "{}|{}",
+        base.0,
+        ingest_config_signature(config, &asset.media_type)
+    ))
+}
+
 // ── list_docs / inspect_doc / inspect_chunk ───────────────────────────────

 pub fn list_docs(filter: DocFilter) -> anyhow::Result<Vec<DocSummary>> {
@@ -3429,3 +3693,337 @@ fn check_kebabignore_match(
        .is_ignore()
 }

+
+#[cfg(test)]
+mod ingest_config_signature_tests {
+    //! v0.26.2: unit tests for [`ingest_config_signature`] — the
+    //! ingest-output-affecting config fingerprint that is folded into the
+    //! effective `parser_version` so that changing any setting that alters
+    //! the produced chunks/embeddings auto-re-indexes the affected assets,
+    //! while changes to unrelated settings (search/rag/ui/…) do not.
+
+    use kebab_config::Config;
+    use kebab_core::{ImageType, MediaType};
+
+    use super::ingest_config_signature;
+
+    fn img() -> MediaType {
+        MediaType::Image(ImageType::Png)
+    }
+    fn pdf() -> MediaType {
+        MediaType::Pdf
+    }
+    fn code() -> MediaType {
+        MediaType::Code("rust".to_string())
+    }
+    fn md() -> MediaType {
+        MediaType::Markdown
+    }
+
+    /// The signature is deterministic: same config + same media → same string.
+    #[test]
+    fn deterministic_for_unchanged_config() {
+        let c = Config::defaults();
+        for m in [md(), img(), pdf(), code()] {
+            assert_eq!(
+                ingest_config_signature(&c, &m),
+                ingest_config_signature(&c, &m),
+                "signature must be stable for {m:?}"
+            );
+        }
+    }
+
+    /// Changing a common chunking parameter changes the signature for EVERY
+    /// media type (re-chunk cascade).
+    #[test]
+    fn chunking_change_invalidates_all_types() {
+        let base = Config::defaults();
+        let mut bumped = base.clone();
+        bumped.chunking.target_tokens += 100;
+        for m in [md(), img(), pdf(), code()] {
+            assert_ne!(
+                ingest_config_signature(&base, &m),
+                ingest_config_signature(&bumped, &m),
+                "target_tokens change must invalidate {m:?}"
+            );
+        }
+
+        let mut overlap = base.clone();
+        overlap.chunking.overlap_tokens += 10;
+        assert_ne!(
+            ingest_config_signature(&base, &md()),
+            ingest_config_signature(&overlap, &md())
+        );
+
+        let mut headings = base.clone();
+        headings.chunking.respect_markdown_headings = !base.chunking.respect_markdown_headings;
+        assert_ne!(
+            ingest_config_signature(&base, &md()),
+            ingest_config_signature(&headings, &md())
+        );
+    }
+
+    /// Image OCR toggle (off→on) changes only the image signature; pdf / code
+    /// / markdown are unaffected.
+    #[test]
+    fn image_ocr_toggle_invalidates_image_only() {
+        let base = Config::defaults();
+        assert!(!base.image.ocr.enabled, "default OCR is off");
+        let mut on = base.clone();
+        on.image.ocr.enabled = true;
+
+        assert_ne!(
+            ingest_config_signature(&base, &img()),
+            ingest_config_signature(&on, &img()),
+            "image OCR toggle must invalidate images"
+        );
+        for m in [md(), pdf(), code()] {
+            assert_eq!(
+                ingest_config_signature(&base, &m),
+                ingest_config_signature(&on, &m),
+                "image OCR toggle must NOT touch {m:?}"
+            );
+        }
+    }
+
+    /// When OCR is enabled, changing the OCR model changes the image
+    /// signature; when OCR is off, the model field is irrelevant.
+    #[test]
+    fn image_ocr_model_matters_only_when_enabled() {
+        let mut off_a = Config::defaults();
+        let mut off_b = off_a.clone();
+        off_b.image.ocr.model = "some-other-model".to_string();
+        assert_eq!(
+            ingest_config_signature(&off_a, &img()),
+            ingest_config_signature(&off_b, &img()),
+            "OCR model is irrelevant while OCR is off"
+        );
+
+        off_a.image.ocr.enabled = true;
+        let mut on_b = off_a.clone();
+        on_b.image.ocr.model = "some-other-model".to_string();
+        assert_ne!(
+            ingest_config_signature(&off_a, &img()),
+            ingest_config_signature(&on_b, &img()),
+            "OCR model change matters while OCR is on"
+        );
+    }
+
+    /// Image caption toggle + prompt-template-version change invalidate images.
+    #[test]
+    fn image_caption_toggle_and_prompt_invalidate_image() {
+        let base = Config::defaults();
+        let mut on = base.clone();
+        on.image.caption.enabled = true;
+        assert_ne!(
+            ingest_config_signature(&base, &img()),
+            ingest_config_signature(&on, &img())
+        );
+
+        let mut prompt = on.clone();
+        prompt.image.caption.prompt_template_version = "caption-v9".to_string();
+        assert_ne!(
+            ingest_config_signature(&on, &img()),
+            ingest_config_signature(&prompt, &img()),
+            "caption prompt version change matters while caption is on"
+        );
+    }
+
+    /// PDF OCR `enabled` and `always_on` both invalidate PDFs (either turns
+    /// OCR on); they do not touch other media types.
+    #[test]
+    fn pdf_ocr_toggle_invalidates_pdf_only() {
+        let base = Config::defaults();
+        let mut enabled = base.clone();
+        enabled.pdf.ocr.enabled = true;
+        assert_ne!(
+            ingest_config_signature(&base, &pdf()),
+            ingest_config_signature(&enabled, &pdf()),
+            "pdf.ocr.enabled toggle must invalidate PDFs"
+        );
+
+        let mut always = base.clone();
+        always.pdf.ocr.always_on = true;
+        assert_ne!(
+            ingest_config_signature(&base, &pdf()),
+            ingest_config_signature(&always, &pdf()),
+            "pdf.ocr.always_on toggle must invalidate PDFs"
+        );
+
+        for m in [md(), img(), code()] {
+            assert_eq!(
+                ingest_config_signature(&base, &m),
+                ingest_config_signature(&enabled, &m),
+                "pdf OCR toggle must NOT touch {m:?}"
+            );
+        }
+    }
+
+    /// Each `[ingest.code]` option change invalidates code assets only.
+    #[test]
+    fn code_options_invalidate_code_only() {
+        let base = Config::defaults();
+
+        let mut variants = Vec::new();
+        let mut v = base.clone();
+        v.ingest.code.skip_generated_header = !base.ingest.code.skip_generated_header;
+        variants.push(v);
+        let mut v = base.clone();
+        v.ingest.code.max_file_bytes += 1;
+        variants.push(v);
+        let mut v = base.clone();
+        v.ingest.code.max_file_lines += 1;
+        variants.push(v);
+        let mut v = base.clone();
+        v.ingest.code.extra_skip_globs.push("**/vendor/**".to_string());
+        variants.push(v);
+        let mut v = base.clone();
+        v.ingest.code.ast_chunk_max_lines += 1;
+        variants.push(v);
+        let mut v = base.clone();
+        v.ingest.code.fallback_lines_per_chunk += 1;
+        variants.push(v);
+        let mut v = base.clone();
+        v.ingest.code.fallback_lines_overlap += 1;
+        variants.push(v);
+
+        for v in &variants {
+            assert_ne!(
+                ingest_config_signature(&base, &code()),
+                ingest_config_signature(v, &code()),
+                "code option change must invalidate code assets"
+            );
+            // ...but must NOT touch md / image / pdf.
+            for m in [md(), img(), pdf()] {
+                assert_eq!(
+                    ingest_config_signature(&base, &m),
+                    ingest_config_signature(v, &m),
+                    "code option change must NOT touch {m:?}"
+                );
+            }
+        }
+    }
+
+    /// Regression guard: search / rag / nli / ui / logging / storage /
+    /// workspace settings — and ingest runtime-only knobs that do NOT change
+    /// indexed output — never change the signature for ANY media type.
+    #[test]
+    fn unrelated_settings_never_invalidate() {
+        let base = Config::defaults();
+        let mut other = base.clone();
+        // search
+        other.search.default_k += 5;
+        other.search.rrf_k += 1;
+        other.search.snippet_chars += 10;
+        // rag
+        other.rag.score_gate += 0.1;
+        other.rag.prompt_template_version = "rag-v99".to_string();
+        // ui
+        other.ui.theme = "light".to_string();
+        // image runtime-only (non-output) knobs
+        other.image.ocr.max_pixels += 100;
+        other.image.ocr.languages.push("jpn".to_string());
+        other.image.ocr.request_timeout_secs += 10;
+        // pdf runtime-only knobs
+        other.pdf.ocr.max_pixels += 100;
+        other.pdf.ocr.request_timeout_secs += 10;
+        other.pdf.ocr.languages.push("jpn".to_string());
+
+        for m in [md(), img(), pdf(), code()] {
+            assert_eq!(
+                ingest_config_signature(&base, &m),
+                ingest_config_signature(&other, &m),
+                "unrelated/runtime-only settings must NOT invalidate {m:?}"
+            );
+        }
+    }
+
+    // ── v0.27.0 (T9): engine + engine_version cascade ─────────────────────
+
+    /// (a) Switching the engine (ollama-vision → paddle-onnx) with the SAME
+    /// model id changes the image signature — different engines produce
+    /// different output even from an identically-named model.
+    #[test]
+    fn image_ocr_engine_switch_invalidates_image() {
+        let mut ollama = Config::defaults();
+        ollama.image.ocr.enabled = true;
+        // same `model` string on both — only the engine differs
+        let mut paddle = ollama.clone();
+        paddle.image.ocr.engine = "paddle-onnx".to_string();
+        assert_ne!(
+            ingest_config_signature(&ollama, &img()),
+            ingest_config_signature(&paddle, &img()),
+            "engine switch with identical model must invalidate images"
+        );
+    }
+
+    /// (b) A different engine_version (here: a different ollama model id, which
+    /// the signature folds into `ollama/{model}`) changes the image signature.
+    #[test]
+    fn image_ocr_engine_version_change_invalidates_image() {
+        let mut a = Config::defaults();
+        a.image.ocr.enabled = true;
+        a.image.ocr.model = "gemma4:e4b".to_string();
+        let mut b = a.clone();
+        b.image.ocr.model = "qwen2.5vl:3b".to_string();
+        assert_ne!(
+            ingest_config_signature(&a, &img()),
+            ingest_config_signature(&b, &img()),
+            "engine_version change must invalidate images"
+        );
+    }
+
+    /// (b') For the paddle-onnx engine, pointing at a different model asset
+    /// (override path) yields a different engine_version → different signature.
+    #[test]
+    fn image_ocr_paddle_model_path_change_invalidates_image() {
+        let mut base = Config::defaults();
+        base.image.ocr.enabled = true;
+        base.image.ocr.engine = "paddle-onnx".to_string();
+        let mut overridden = base.clone();
+        overridden.image.ocr.det_model = Some("/some/other/det.onnx".to_string());
+        assert_ne!(
+            ingest_config_signature(&base, &img()),
+            ingest_config_signature(&overridden, &img()),
+            "paddle-onnx model path change must invalidate images"
+        );
+    }
+
+    /// (c) Unrelated settings leave the paddle-onnx image signature stable
+    /// (engine_version is memoized + deterministic for a fixed asset triple).
+    #[test]
+    fn paddle_image_signature_stable_for_unrelated_change() {
+        let mut base = Config::defaults();
+        base.image.ocr.enabled = true;
+        base.image.ocr.engine = "paddle-onnx".to_string();
+        let mut other = base.clone();
+        other.search.default_k += 3;
+        other.image.ocr.max_pixels += 100; // runtime-only knob
+        assert_eq!(
+            ingest_config_signature(&base, &img()),
+            ingest_config_signature(&other, &img()),
+            "unrelated/runtime-only changes must not invalidate paddle images"
+        );
+    }
+
+    /// PDF OCR: engine switch with the same model invalidates pdf only.
+    #[test]
+    fn pdf_ocr_engine_switch_invalidates_pdf() {
+        let mut ollama = Config::defaults();
+        ollama.pdf.ocr.enabled = true;
+        let mut paddle = ollama.clone();
+        paddle.pdf.ocr.engine = "paddle-onnx".to_string();
+        assert_ne!(
+            ingest_config_signature(&ollama, &pdf()),
+            ingest_config_signature(&paddle, &pdf()),
+            "pdf engine switch must invalidate pdf"
+        );
+        for m in [md(), img(), code()] {
+            assert_eq!(
+                ingest_config_signature(&ollama, &m),
+                ingest_config_signature(&paddle, &m),
+                "pdf engine switch must NOT touch {m:?}"
+            );
+        }
+    }
+}
--- a/crates/kebab-app/tests/code_ingest_smoke.rs
+++ b/crates/kebab-app/tests/code_ingest_smoke.rs
@@ -52,7 +52,9 @@ fn rust_file_ingests_and_searches_as_code_citation() {
        "at least one chunk expected: {code_item:?}"
    );
    assert_eq!(
-        code_item.parser_version.as_ref().map(|p| p.0.as_str()),
+        code_item.parser_version
+            .as_ref()
+            .map(|p| p.0.split('|').next().unwrap()),
        Some("code-rust-v1"),
        "parser_version must be code-rust-v1"
    );
@@ -185,7 +187,9 @@ fn python_file_ingests_and_searches_as_code_citation() {
        .find(|i| i.doc_path.0.ends_with("metrics.py"))
        .expect("metrics.py item");
    assert_eq!(
-        py_item.parser_version.as_ref().map(|p| p.0.as_str()),
+        py_item.parser_version
+            .as_ref()
+            .map(|p| p.0.split('|').next().unwrap()),
        Some("code-python-v1"),
        "parser_version must be code-python-v1"
    );
@@ -261,7 +265,9 @@ fn typescript_file_ingests_and_searches_as_code_citation() {
        .find(|i| i.doc_path.0.ends_with("Foo.ts"))
        .expect("Foo.ts item");
    assert_eq!(
-        ts_item.parser_version.as_ref().map(|p| p.0.as_str()),
+        ts_item.parser_version
+            .as_ref()
+            .map(|p| p.0.split('|').next().unwrap()),
        Some("code-ts-v1"),
        "parser_version must be code-ts-v1"
    );
@@ -337,7 +343,9 @@ fn javascript_file_ingests_and_searches_as_code_citation() {
        .find(|i| i.doc_path.0.ends_with("Bar.js"))
        .expect("Bar.js item");
    assert_eq!(
-        js_item.parser_version.as_ref().map(|p| p.0.as_str()),
+        js_item.parser_version
+            .as_ref()
+            .map(|p| p.0.split('|').next().unwrap()),
        Some("code-js-v1"),
        "parser_version must be code-js-v1"
    );
@@ -415,7 +423,9 @@ fn go_file_ingests_and_searches_as_code_citation() {
        .find(|i| i.doc_path.0.ends_with("ast.go"))
        .expect("ast.go item present");
    assert_eq!(
-        go_item.parser_version.as_ref().map(|p| p.0.as_str()),
+        go_item.parser_version
+            .as_ref()
+            .map(|p| p.0.split('|').next().unwrap()),
        Some("code-go-v1"),
        "parser_version must be code-go-v1"
    );
@@ -486,7 +496,9 @@ fn java_file_ingests_and_searches_as_code_citation() {
        .find(|i| i.doc_path.0.ends_with("Foo.java"))
        .expect("Foo.java item present");
    assert_eq!(
-        java_item.parser_version.as_ref().map(|p| p.0.as_str()),
+        java_item.parser_version
+            .as_ref()
+            .map(|p| p.0.split('|').next().unwrap()),
        Some("code-java-v1"),
        "parser_version must be code-java-v1"
    );
@@ -561,7 +573,9 @@ fn kotlin_file_ingests_and_searches_as_code_citation() {
        .find(|i| i.doc_path.0.ends_with("Foo.kt"))
        .expect("Foo.kt item present");
    assert_eq!(
-        kt_item.parser_version.as_ref().map(|p| p.0.as_str()),
+        kt_item.parser_version
+            .as_ref()
+            .map(|p| p.0.split('|').next().unwrap()),
        Some("code-kotlin-v1"),
        "parser_version must be code-kotlin-v1"
    );
@@ -634,7 +648,9 @@ fn tier2_k8s_yaml_ingest_searchable() {
        .find(|i| i.doc_path.0.ends_with("deploy.yaml"))
        .expect("deploy.yaml item present");
    assert_eq!(
-        yaml_item.parser_version.as_ref().map(|p| p.0.as_str()),
+        yaml_item.parser_version
+            .as_ref()
+            .map(|p| p.0.split('|').next().unwrap()),
        Some("none-v1"),
        "parser_version must be none-v1"
    );
@@ -717,7 +733,9 @@ fn tier2_dockerfile_ingest_searchable() {
        .find(|i| i.doc_path.0.ends_with("Dockerfile"))
        .expect("Dockerfile item present");
    assert_eq!(
-        df_item.parser_version.as_ref().map(|p| p.0.as_str()),
+        df_item.parser_version
+            .as_ref()
+            .map(|p| p.0.split('|').next().unwrap()),
        Some("none-v1"),
        "parser_version must be none-v1"
    );
@@ -800,7 +818,9 @@ fn tier2_cargo_toml_ingest_searchable() {
        .find(|i| i.doc_path.0.ends_with("Cargo.toml"))
        .expect("Cargo.toml item present");
    assert_eq!(
-        toml_item.parser_version.as_ref().map(|p| p.0.as_str()),
+        toml_item.parser_version
+            .as_ref()
+            .map(|p| p.0.split('|').next().unwrap()),
        Some("none-v1"),
        "parser_version must be none-v1"
    );
@@ -883,7 +903,9 @@ fn tier3_shell_ingest_searchable() {
        .find(|i| i.doc_path.0.ends_with("deploy.sh"))
        .expect("deploy.sh item present");
    assert_eq!(
-        sh_item.parser_version.as_ref().map(|p| p.0.as_str()),
+        sh_item.parser_version
+            .as_ref()
+            .map(|p| p.0.split('|').next().unwrap()),
        Some("none-v1"),
        "parser_version must be none-v1 for shell (Tier 3 direct)"
    );
@@ -974,7 +996,9 @@ fn tier3_yaml_fallback_picks_up_non_k8s_yaml() {
        .find(|i| i.doc_path.0.ends_with("docker-compose.yml"))
        .expect("docker-compose.yml item present");
    assert_eq!(
-        yaml_item.parser_version.as_ref().map(|p| p.0.as_str()),
+        yaml_item.parser_version
+            .as_ref()
+            .map(|p| p.0.split('|').next().unwrap()),
        Some("none-v1"),
        "parser_version must be none-v1 after Tier 3 fallback"
    );
@@ -1144,7 +1168,9 @@ fn tier1_c_ingest_searchable() {
        .find(|i| i.doc_path.0.ends_with("parser.c"))
        .expect("parser.c item present");
    assert_eq!(
-        c_item.parser_version.as_ref().map(|p| p.0.as_str()),
+        c_item.parser_version
+            .as_ref()
+            .map(|p| p.0.split('|').next().unwrap()),
        Some("code-c-v2"),
        "parser_version must be code-c-v2 (v0.17.0 PR-B: typedef-wrapped struct/enum/union 이 typedef alias unit 으로 방출)"
    );
@@ -1228,7 +1254,9 @@ fn tier1_cpp_ingest_searchable() {
        .find(|i| i.doc_path.0.ends_with("chunker.cpp"))
        .expect("chunker.cpp item present");
    assert_eq!(
-        cpp_item.parser_version.as_ref().map(|p| p.0.as_str()),
+        cpp_item.parser_version
+            .as_ref()
+            .map(|p| p.0.split('|').next().unwrap()),
        Some("code-cpp-v1"),
        "parser_version must be code-cpp-v1"
    );
--- a/crates/kebab-app/tests/common/mock_ocr.rs
+++ b/crates/kebab-app/tests/common/mock_ocr.rs
@@ -39,6 +39,11 @@ impl OcrEngine for MockOcrEngine {
        "mock-v1".to_string()
    }

+    #[allow(clippy::unnecessary_literal_bound)]
+    fn model(&self) -> &str {
+        "mock-model"
+    }
+
    fn recognize(&self, _img: &[u8], _hint: Option<&Lang>) -> Result<OcrText> {
        if self.fail {
            anyhow::bail!("mock failure");
--- a/crates/kebab-app/tests/config_invalidation.rs
+++ b/crates/kebab-app/tests/config_invalidation.rs
@@ -0,0 +1,148 @@
+//! v0.26.2: ingest-config invalidation — changing a setting that affects
+//! ingest output auto-re-indexes the affected assets on the next ingest
+//! (no `--force-reingest`), while changing an unrelated setting does not.
+//!
+//! These end-to-end tests exercise the model-free signals (chunking +
+//! `[ingest.code]` options vs `search` settings). The exhaustive per-setting
+//! mapping (image OCR / caption, pdf.ocr, code options, search/rag/ui
+//! invariance) is unit-tested in
+//! `kebab-app/src/lib.rs::ingest_config_signature_tests` — those toggles
+//! (OCR/caption) require a live vision endpoint to ingest, so the wiring is
+//! verified here via the signature-driven chunking path that shares the same
+//! `effective_parser_version` plumbing.
+
+mod common;
+
+use common::TestEnv;
+
+use kebab_app::{IngestOpts, ingest_with_config, ingest_with_config_opts};
+use kebab_core::IngestItemKind;
+
+/// Seed a workspace with a markdown + a rust file so both the markdown and
+/// the code ingest paths are exercised. Returns the first-ingest report.
+fn seed_and_first_ingest(env: &TestEnv) -> kebab_core::IngestReport {
+    std::fs::write(
+        env.workspace_root.join("demo.rs"),
+        "/// adds two integers\npub fn add(a: i32, b: i32) -> i32 {\n    a + b\n}\n",
+    )
+    .unwrap();
+    let first = ingest_with_config(env.config.clone(), env.scope(), false).expect("first ingest");
+    assert_eq!(first.errors, 0, "first ingest must not error: {first:?}");
+    assert!(first.new >= 1, "first ingest creates docs: {first:?}");
+    assert_eq!(first.unchanged, 0, "first ingest has no unchanged: {first:?}");
+    first
+}
+
+fn reingest(env: &TestEnv) -> kebab_core::IngestReport {
+    ingest_with_config_opts(env.config.clone(), env.scope(), false, IngestOpts::default())
+        .expect("re-ingest")
+}
+
+/// Re-running with the identical config skips every asset (no spurious
+/// re-index). Regression guard for over-invalidation.
+#[test]
+fn identical_config_skips_all_assets() {
+    let env = TestEnv::lexical_only();
+    let first = seed_and_first_ingest(&env);
+    let scanned = first.scanned;
+
+    let second = reingest(&env);
+    assert_eq!(second.scanned, scanned);
+    assert_eq!(second.new, 0, "no new docs: {second:?}");
+    assert_eq!(second.updated, 0, "nothing re-indexed: {second:?}");
+    assert_eq!(second.unchanged, scanned, "every doc Unchanged: {second:?}");
+    assert_eq!(second.errors, 0);
+}
+
+/// Changing a common chunking parameter re-indexes EVERY media type
+/// (markdown + code here) without `--force-reingest`.
+#[test]
+fn chunking_change_reindexes_all_types() {
+    let mut env = TestEnv::lexical_only();
+    let first = seed_and_first_ingest(&env);
+    let scanned = first.scanned;
+
+    // Bump target_tokens — folds into every type's signature.
+    env.config.chunking.target_tokens += 100;
+
+    let second = reingest(&env);
+    assert_eq!(second.scanned, scanned);
+    assert_eq!(second.new, 0, "no new docs: {second:?}");
+    assert_eq!(
+        second.unchanged, 0,
+        "chunking change must re-index all: {second:?}"
+    );
+    assert_eq!(
+        second.updated, scanned,
+        "every doc re-indexed as Updated: {second:?}"
+    );
+    assert_eq!(second.errors, 0);
+}
+
+/// Changing an `[ingest.code]` option re-indexes only the code asset; the
+/// markdown assets stay Unchanged.
+#[test]
+fn code_option_change_reindexes_code_only() {
+    let mut env = TestEnv::lexical_only();
+    let first = seed_and_first_ingest(&env);
+    let scanned = first.scanned;
+
+    // Raise max_file_lines (keeps the tiny demo.rs in-scope; only the code
+    // signature changes).
+    env.config.ingest.code.max_file_lines += 1000;
+
+    let second = reingest(&env);
+    assert_eq!(second.scanned, scanned);
+    assert_eq!(second.new, 0, "no new docs: {second:?}");
+    assert_eq!(second.errors, 0);
+    assert_eq!(
+        second.updated, 1,
+        "exactly the code asset re-indexed: {second:?}"
+    );
+    assert_eq!(
+        second.unchanged,
+        scanned - 1,
+        "all markdown assets stay Unchanged: {second:?}"
+    );
+
+    let items = second.items.as_ref().expect("items present");
+    let code = items
+        .iter()
+        .find(|i| i.doc_path.0.ends_with("demo.rs"))
+        .expect("demo.rs item");
+    assert_eq!(
+        code.kind,
+        IngestItemKind::Updated,
+        "demo.rs must be re-indexed: {code:?}"
+    );
+    for i in items.iter().filter(|i| i.doc_path.0.ends_with(".md")) {
+        assert_eq!(
+            i.kind,
+            IngestItemKind::Unchanged,
+            "markdown must be Unchanged: {i:?}"
+        );
+    }
+}
+
+/// Regression guard: changing a non-ingest setting (`search.default_k`) does
+/// NOT re-index anything.
+#[test]
+fn search_setting_change_reindexes_nothing() {
+    let mut env = TestEnv::lexical_only();
+    let first = seed_and_first_ingest(&env);
+    let scanned = first.scanned;
+
+    env.config.search.default_k += 5;
+    env.config.search.snippet_chars += 50;
+    env.config.rag.score_gate = 0.5;
+
+    let second = reingest(&env);
+    assert_eq!(second.scanned, scanned);
+    assert_eq!(
+        second.unchanged, scanned,
+        "search/rag changes must not re-index: {second:?}"
+    );
+    assert_eq!(second.updated, 0, "nothing re-indexed: {second:?}");
+    assert_eq!(second.new, 0);
+    assert_eq!(second.errors, 0);
+}
--- a/crates/kebab-app/tests/pdf_pipeline.rs
+++ b/crates/kebab-app/tests/pdf_pipeline.rs
@@ -162,7 +162,9 @@ fn ingest_3_page_pdf_produces_one_doc_and_per_page_chunks() {
        "one chunk per non-empty page"
    );
    assert_eq!(
-        pdf_item.parser_version.as_ref().map(|p| p.0.as_str()),
+        pdf_item.parser_version
+            .as_ref()
+            .map(|p| p.0.split('|').next().unwrap()),
        Some("pdf-text-v1")
    );
    assert_eq!(
@@ -477,7 +479,10 @@ fn inspect_doc_surfaces_page_spans() {
        .find(|i| i.doc_path.0.ends_with("inspect.pdf"))
        .unwrap();
    let doc = kebab_app::inspect_doc_with_config(cfg, pdf_item.doc_id.as_ref().unwrap()).unwrap();
-    assert_eq!(doc.parser_version.0, "pdf-text-v1");
+    // v0.26.2: stored parser_version is now `pdf-text-v1|<ingest-config-sig>`
+    // (the signature folds chunking / pdf.ocr settings for skip detection).
+    // Assert the base identity by taking the prefix before the first '|'.
+    assert_eq!(doc.parser_version.0.split('|').next().unwrap(), "pdf-text-v1");
    assert_eq!(doc.blocks.len(), 3);
    for block in &doc.blocks {
        match block {
--- a/crates/kebab-config/src/lib.rs
+++ b/crates/kebab-config/src/lib.rs
@@ -377,6 +377,36 @@ pub struct OcrCfg {
    /// `86400`).
    #[serde(default = "default_ocr_request_timeout_secs")]
    pub request_timeout_secs: u64,
+
+    // ── paddle-onnx engine overrides (v0.27.0) ──────────────────────────
+    // Only consulted when `engine == "paddle-onnx"`; the ollama-vision
+    // engine ignores them. All `#[serde(default)]` so pre-v0.27 config
+    // files load unchanged.
+    /// Override path to the detection ONNX model. `None` → bundled
+    /// `assets/paddleocr-onnx/ppocrv5_mobile_det.onnx` (or the directory
+    /// named by `KEBAB_IMAGE_OCR_MODEL_DIR`).
+    #[serde(default)]
+    pub det_model: Option<String>,
+    /// Override path to the recognition ONNX model. `None` → bundled
+    /// `assets/paddleocr-onnx/korean_ppocrv5_mobile_rec.onnx`.
+    #[serde(default)]
+    pub rec_model: Option<String>,
+    /// Override path to the character dictionary. `None` → bundled
+    /// `assets/paddleocr-onnx/korean_dict.txt`.
+    #[serde(default)]
+    pub dict: Option<String>,
+    /// DBNet detection box score threshold (0.0..=1.0). Boxes whose mean
+    /// probability is below this are dropped. Default `0.3`.
+    #[serde(default = "default_ocr_score_thresh")]
+    pub score_thresh: f32,
+    /// Polygon unclip ratio applied to each detected box before crop.
+    /// Larger = more padding around the text. Default `1.5`.
+    #[serde(default = "default_ocr_unclip_ratio")]
+    pub unclip_ratio: f32,
+    /// Hard cap on detected boxes per image (runaway guard). Extra boxes
+    /// past this count are truncated with a warning. Default `1000`.
+    #[serde(default = "default_ocr_max_boxes")]
+    pub max_boxes: usize,
 }

 impl OcrCfg {
@@ -389,10 +419,29 @@ impl OcrCfg {
            languages: vec!["eng".to_string(), "kor".to_string()],
            max_pixels: 1600,
            request_timeout_secs: default_ocr_request_timeout_secs(),
+            det_model: None,
+            rec_model: None,
+            dict: None,
+            score_thresh: default_ocr_score_thresh(),
+            unclip_ratio: default_ocr_unclip_ratio(),
+            max_boxes: default_ocr_max_boxes(),
        }
    }
 }

+/// paddle-onnx DBNet box score threshold default. See [`OcrCfg::score_thresh`].
+fn default_ocr_score_thresh() -> f32 {
+    0.3
+}
+/// paddle-onnx unclip ratio default. See [`OcrCfg::unclip_ratio`].
+fn default_ocr_unclip_ratio() -> f32 {
+    1.5
+}
+/// paddle-onnx box-count cap default. See [`OcrCfg::max_boxes`].
+fn default_ocr_max_boxes() -> usize {
+    1000
+}
+
 /// v0.17.2 post-dogfood: matches the legacy hard-coded ceiling so
 /// existing configs that omit the field keep behaving identically.
 /// Overridable per config / `KEBAB_IMAGE_OCR_REQUEST_TIMEOUT_SECS`.
@@ -512,7 +561,9 @@ pub struct PdfOcrCfg {
    /// scanned pages only. `true` — vision LLM 호출 on every page
    /// (vector PDF 의 dual-text confidence boost — doubles chunk count).
    pub always_on: bool,
-    /// Engine identifier. v1 only ships `"ollama-vision"`.
+    /// Engine identifier: `"ollama-vision"` or `"paddle-onnx"`. When set to
+    /// `"paddle-onnx"`, model paths and tuning knobs are read from
+    /// `[image.ocr]`, not `[pdf.ocr]` — PaddleOCR has no PDF-specific tuning.
    pub engine: String,
    /// Vision model id. Default `"qwen2.5vl:3b"` per PoC (§3.5 family
    /// asymmetry vs image OCR's gemma4:e4b is acknowledged).
@@ -1098,6 +1149,34 @@ impl Config {
                        self.image.ocr.request_timeout_secs = n;
                    }
                }
+                // paddle-onnx engine overrides (v0.27.0). Empty string → None
+                // (fall back to bundled / KEBAB_IMAGE_OCR_MODEL_DIR).
+                "KEBAB_IMAGE_OCR_DET_MODEL" => {
+                    self.image.ocr.det_model =
+                        if v.is_empty() { None } else { Some(v.clone()) };
+                }
+                "KEBAB_IMAGE_OCR_REC_MODEL" => {
+                    self.image.ocr.rec_model =
+                        if v.is_empty() { None } else { Some(v.clone()) };
+                }
+                "KEBAB_IMAGE_OCR_DICT" => {
+                    self.image.ocr.dict = if v.is_empty() { None } else { Some(v.clone()) };
+                }
+                "KEBAB_IMAGE_OCR_SCORE_THRESH" => {
+                    if let Ok(f) = v.parse::<f32>() {
+                        self.image.ocr.score_thresh = f;
+                    }
+                }
+                "KEBAB_IMAGE_OCR_UNCLIP_RATIO" => {
+                    if let Ok(f) = v.parse::<f32>() {
+                        self.image.ocr.unclip_ratio = f;
+                    }
+                }
+                "KEBAB_IMAGE_OCR_MAX_BOXES" => {
+                    if let Ok(n) = v.parse::<usize>() {
+                        self.image.ocr.max_boxes = n;
+                    }
+                }

                // image.caption (P6-3)
                "KEBAB_IMAGE_CAPTION_ENABLED" => {
--- a/crates/kebab-parse-image/Cargo.toml
+++ b/crates/kebab-parse-image/Cargo.toml
@@ -35,6 +35,24 @@ kamadak-exif = "0.6"
 # transitive tokio runtime is brought in once.
 reqwest      = { version = "0.12", default-features = false, features = ["blocking", "json", "rustls-tls"] }
 base64       = { workspace = true }
+thiserror    = { workspace = true }
+# paddle-onnx OCR engine (PP-OCRv5, in-process). We reuse the workspace ort
+# pin (=2.0.0-rc.9) so the ONNX Runtime native lib stays single-versioned with
+# fastembed / kebab-nli (oar-ocr is intentionally NOT a dep — it would pull
+# ort rc.12 + ndarray 0.17, splitting the native `links` and threatening the
+# embedding stack). `download-binaries` extends the pin the same way
+# `kebab-nli/Cargo.toml:23` does: this crate isn't in fastembed's build graph,
+# so a standalone `cargo test -p kebab-parse-image` needs it to link onnxruntime.
+ort          = { workspace = true, features = ["ndarray", "download-binaries"] }
+ndarray      = { workspace = true }
+# blake3: engine_version hash over the bundled det/rec/dict assets (computed
+# once at OnnxPaddleOcr construction, cached — `ingest_config_signature` calls
+# engine_version() per asset).
+blake3       = { workspace = true }
+# imageproc: connected-components / contours for DBNet det post-processing.
+# min-area rotated-rect (rotating calipers) and polygon unclip are implemented
+# in pure Rust (clipper2 is C++ FFI — would break the single-binary guarantee).
+imageproc    = "0.25"

 [dev-dependencies]
 tempfile     = { workspace = true }
--- a/crates/kebab-parse-image/assets/paddleocr-onnx/NOTICE
+++ b/crates/kebab-parse-image/assets/paddleocr-onnx/NOTICE
@@ -0,0 +1,33 @@
+PP-OCRv5 mobile ONNX models bundled with kebab (paddle-onnx OCR engine)
+=======================================================================
+
+These model weights and the recognition dictionary are derived from
+PaddleOCR (https://github.com/PaddlePaddle/PaddleOCR), licensed under the
+Apache License, Version 2.0.
+
+  Copyright (c) PaddlePaddle Authors.
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use these files except in compliance with the License.
+  You may obtain a copy of the License at
+      http://www.apache.org/licenses/LICENSE-2.0
+
+Files
+-----
+  ppocrv5_mobile_det.onnx          PP-OCRv5_mobile detection model (DBNet)
+  korean_ppocrv5_mobile_rec.onnx   korean_PP-OCRv5_mobile recognition model (CTC)
+  korean_dict.txt                  recognition dictionary (11,945 chars: KR + Latin + digits + symbols)
+
+These were converted from the official PaddlePaddle inference models to ONNX
+via paddle2onnx for in-process execution with onnxruntime (`ort`). No model
+architecture or weights were modified; only the serialization format changed.
+
+The recognition CTC class layout (empirically confirmed, see
+tests/golden/ctc_rec_golden.json):
+  index 0          = CTC blank
+  index 1..11945   = korean_dict.txt line N -> class N (dict[N-1])
+  index 11946      = space ' '
+  total classes    = 11947 (= 11945 dict + blank + space)
+
+If any post-processing source (min-area-rect / polygon unclip) is later
+ported verbatim from oar-ocr (Apache-2.0), record the per-file provenance
+here as required by the Apache-2.0 attribution clause.
--- a/crates/kebab-parse-image/assets/paddleocr-onnx/korean_dict.txt
+++ b/crates/kebab-parse-image/assets/paddleocr-onnx/korean_dict.txt
--- a/crates/kebab-parse-image/assets/paddleocr-onnx/korean_ppocrv5_mobile_rec.onnx
+++ b/crates/kebab-parse-image/assets/paddleocr-onnx/korean_ppocrv5_mobile_rec.onnx
--- a/crates/kebab-parse-image/assets/paddleocr-onnx/ppocrv5_mobile_det.onnx
+++ b/crates/kebab-parse-image/assets/paddleocr-onnx/ppocrv5_mobile_det.onnx
--- a/crates/kebab-parse-image/src/lib.rs
+++ b/crates/kebab-parse-image/src/lib.rs
@@ -30,9 +30,11 @@ mod dims;
 mod exif_extract;
 mod image_prep;
 pub mod ocr;
+pub mod paddle_onnx;

 pub use caption::{apply_caption, caption_image};
-pub use ocr::{OcrEngine, OllamaVisionOcr, apply_ocr};
+pub use ocr::{OLLAMA_VISION_ENGINE, OcrEngine, OllamaVisionOcr, apply_ocr};
+pub use paddle_onnx::{ModelPaths, OnnxPaddleOcr, PADDLE_ONNX_ENGINE, engine_version_for_config};

 use anyhow::{Context, Result};
 use kebab_core::{
--- a/crates/kebab-parse-image/src/ocr.rs
+++ b/crates/kebab-parse-image/src/ocr.rs
@@ -65,6 +65,13 @@ pub trait OcrEngine: Send + Sync {
    /// through to engines that benefit from it (Tesseract languages,
    /// LLM prompt steering); ignore otherwise.
    fn recognize(&self, image_bytes: &[u8], lang_hint: Option<&Lang>) -> Result<OcrText>;
+
+    /// Human-facing model label for the ingest progress display
+    /// (`AssetPhase{phase:"ocr", model}`). Distinct from
+    /// [`engine_version`](Self::engine_version), which is the cache-key
+    /// hash. E.g. `"gemma4:e4b"` (ollama-vision) or `"ppocrv5-mobile-kor"`
+    /// (paddle-onnx).
+    fn model(&self) -> &str;
 }

 /// Mutate `block.ocr` in place by running `engine` over `image_bytes`,
@@ -209,13 +216,6 @@ impl OllamaVisionOcr {
        self.max_pixels
    }

-    /// The Ollama model id this engine drives (e.g. `gemma4:e4b`).
-    /// Surfaced so the ingest progress display can name the model
-    /// running a slow OCR phase (`AssetPhase{phase:"ocr", model}`).
-    pub fn model(&self) -> &str {
-        &self.model
-    }
-
    fn build_prompt(&self, lang_hint: Option<&Lang>) -> String {
        let langs = if self.languages.is_empty() {
            "any".to_string()
@@ -247,6 +247,10 @@ impl OcrEngine for OllamaVisionOcr {
        format!("ollama/{}", self.model)
    }

+    fn model(&self) -> &str {
+        &self.model
+    }
+
    fn recognize(&self, image_bytes: &[u8], lang_hint: Option<&Lang>) -> Result<OcrText> {
        let (prepared, w, h) = image_prep::downscale_to_png(image_bytes, self.max_pixels)
            .context("preparing image for OCR")?;
--- a/crates/kebab-parse-image/src/paddle_onnx.rs
+++ b/crates/kebab-parse-image/src/paddle_onnx.rs
@@ -0,0 +1,985 @@
+//! PP-OCRv5 ONNX OCR engine — in-process detection + recognition on the
+//! workspace-pinned `ort` (=2.0.0-rc.9), no Python runtime, no oar-ocr
+//! production dependency (see crate-level rationale + `assets/paddleocr-onnx/NOTICE`).
+//!
+//! Pipeline (`recognize`):
+//! 1. decode (RGB) + downscale long edge to `max_pixels`
+//! 2. det: ImageNet-normalized NCHW → DBNet prob map `[1,1,H,W]` → threshold
+//!    0.3 → contours → min-area rect (rotating calipers, pure Rust) →
+//!    unclip(ratio 1.5, pure Rust) → boxes
+//! 3. crop+rectify: perspective warp each rotated box to a horizontal strip
+//! 4. rec: 48×W normalized `(x-0.5)/0.5` → `[1,T,11947]` → CTC greedy decode
+//! 5. assemble reading-order `OcrText`
+//!
+//! ## Confirmed CTC facts (empirically derived in T0a, see
+//! `tests/golden/ctc_rec_golden.json` — do NOT re-derive):
+//!   * rec classes = 11947 = dict(11945) + blank + space
+//!   * index 0       = CTC blank
+//!   * index 1..=11945 = `korean_dict.txt` line N → class N (i.e. `dict[N-1]`)
+//!   * index 11946   = space ' '
+//!
+//! ## rc.9 API notes (differ from rc.12):
+//!   * `try_extract_tensor::<f32>()` → `ArrayViewD<f32>` (`.shape()` / indexing).
+//!   * `Session::run` is called through a `Mutex` guard so the engine is
+//!     `Send + Sync` regardless of `Session`'s own auto-trait status (ingest
+//!     is serial today; the lock is uncontended).
+
+use std::path::{Path, PathBuf};
+use std::sync::Mutex;
+
+use anyhow::{Context, Result};
+use kebab_core::{Lang, OcrRegion, OcrText};
+use ndarray::Array4;
+use ort::session::Session;
+use ort::value::Value;
+
+use crate::ocr::OcrEngine;
+
+/// Engine name written into `OcrText.engine`.
+pub const PADDLE_ONNX_ENGINE: &str = "paddle-onnx";
+
+/// CTC blank class index (confirmed in T0a).
+const CTC_BLANK: usize = 0;
+/// Space class index (confirmed in T0a). `1..=DICT_LINES` map to dict entries.
+const CTC_SPACE: usize = 11946;
+/// `korean_dict.txt` line count (confirmed in T0a).
+const DICT_LINES: usize = 11945;
+/// rec output class count = dict + blank + space (confirmed in T0a).
+const REC_CLASSES: usize = 11947;
+
+/// det long-edge cap before rounding to a multiple of 32 (PaddleOCR default).
+const DET_LIMIT_SIDE_LEN: u32 = 960;
+/// rec input height (PP-OCRv5 mobile).
+const REC_HEIGHT: u32 = 48;
+/// DBNet probability-map binarization threshold. Looser than Paddle's default
+/// `box_thresh` (0.6) to keep recall high on low-contrast Korean text.
+const DET_BIN_THRESH: f32 = 0.3;
+
+/// ImageNet normalization (det preprocessing — RGB).
+const IMAGENET_MEAN: [f32; 3] = [0.485, 0.456, 0.406];
+const IMAGENET_STD: [f32; 3] = [0.229, 0.224, 0.225];
+
+/// PP-OCRv5 ONNX engine. Holds the two ONNX sessions (loaded once) and the
+/// dict. `engine_version` is computed once at construction (blake3 over the
+/// three model assets) and cached — `ingest_config_signature` calls
+/// `engine_version()` per asset, so re-hashing there would be O(assets).
+pub struct OnnxPaddleOcr {
+    det: Mutex<Session>,
+    rec: Mutex<Session>,
+    det_input_name: String,
+    rec_input_name: String,
+    dict: Vec<String>,
+    engine_version: String,
+    score_thresh: f32,
+    unclip_ratio: f32,
+    max_boxes: usize,
+    max_pixels: u32,
+}
+
+impl std::fmt::Debug for OnnxPaddleOcr {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("OnnxPaddleOcr")
+            .field("engine_version", &self.engine_version)
+            .field("dict_lines", &self.dict.len())
+            .field("score_thresh", &self.score_thresh)
+            .field("unclip_ratio", &self.unclip_ratio)
+            .field("max_boxes", &self.max_boxes)
+            .field("max_pixels", &self.max_pixels)
+            .finish_non_exhaustive()
+    }
+}
+
+/// Resolved model-asset paths. Construction is decoupled from `kebab-config`
+/// (T7 adds the `det_model`/`rec_model`/`dict` overrides) so the engine can be
+/// built directly in tests.
+#[derive(Clone, Debug)]
+pub struct ModelPaths {
+    pub det: PathBuf,
+    pub rec: PathBuf,
+    pub dict: PathBuf,
+}
+
+impl ModelPaths {
+    /// Default bundled-asset directory: `KEBAB_IMAGE_OCR_MODEL_DIR` if set,
+    /// else the crate's `assets/paddleocr-onnx/`.
+    pub fn from_default_dir() -> Self {
+        let dir = std::env::var("KEBAB_IMAGE_OCR_MODEL_DIR").map_or_else(
+            |_| Path::new(env!("CARGO_MANIFEST_DIR")).join("assets/paddleocr-onnx"),
+            PathBuf::from,
+        );
+        Self {
+            det: dir.join("ppocrv5_mobile_det.onnx"),
+            rec: dir.join("korean_ppocrv5_mobile_rec.onnx"),
+            dict: dir.join("korean_dict.txt"),
+        }
+    }
+
+    /// Resolve model paths from the `image.ocr` config (T7). Each of
+    /// `det_model` / `rec_model` / `dict` overrides the corresponding bundled
+    /// path when set; unset fields fall back to [`from_default_dir`], so a
+    /// caller can override just one asset.
+    ///
+    /// [`from_default_dir`]: ModelPaths::from_default_dir
+    pub fn from_config(config: &kebab_config::Config) -> Self {
+        let defaults = Self::from_default_dir();
+        let ocr = &config.image.ocr;
+        Self {
+            det: ocr.det_model.as_ref().map(PathBuf::from).unwrap_or(defaults.det),
+            rec: ocr.rec_model.as_ref().map(PathBuf::from).unwrap_or(defaults.rec),
+            dict: ocr.dict.as_ref().map(PathBuf::from).unwrap_or(defaults.dict),
+        }
+    }
+}
+
+impl OnnxPaddleOcr {
+    /// Build from a workspace [`kebab_config::Config`]. Resolves model paths
+    /// from the default bundled directory (T7 will thread config overrides).
+    /// Construction loads both ONNX sessions and hashes the assets — failures
+    /// here are fail-fast (matches the Ollama adapter's construction contract).
+    pub fn new(config: &kebab_config::Config) -> Result<Self> {
+        let paths = ModelPaths::from_config(config);
+        let ocr = &config.image.ocr;
+        Self::from_paths(
+            &paths,
+            ocr.score_thresh,
+            ocr.unclip_ratio,
+            ocr.max_boxes,
+            ocr.max_pixels,
+        )
+    }
+
+    /// Build from explicit asset paths + tuning knobs. Used by tests and by
+    /// `new` after path resolution.
+    pub fn from_paths(
+        paths: &ModelPaths,
+        score_thresh: f32,
+        unclip_ratio: f32,
+        max_boxes: usize,
+        max_pixels: u32,
+    ) -> Result<Self> {
+        let dict = load_dict(&paths.dict)
+            .with_context(|| format!("loading OCR dict from {}", paths.dict.display()))?;
+        // bounds-check: dict length must match the rec class layout
+        // (dict + blank + space). A mismatch means a wrong dict file —
+        // fail at construction rather than mis-decoding silently.
+        if dict.len() != DICT_LINES {
+            anyhow::bail!(
+                "OnnxPaddleOcr: dict has {} lines, expected {DICT_LINES} \
+                 (rec classes {REC_CLASSES} = dict + blank + space)",
+                dict.len()
+            );
+        }
+
+        let engine_version = compute_engine_version(paths)
+            .context("hashing OCR model assets for engine_version")?;
+
+        let det = Session::builder()
+            .context("ort Session::builder (det)")?
+            .commit_from_file(&paths.det)
+            .with_context(|| format!("loading det model {}", paths.det.display()))?;
+        let rec = Session::builder()
+            .context("ort Session::builder (rec)")?
+            .commit_from_file(&paths.rec)
+            .with_context(|| format!("loading rec model {}", paths.rec.display()))?;
+
+        let det_input_name = det
+            .inputs
+            .first()
+            .map(|i| i.name.clone())
+            .context("det model has no inputs")?;
+        let rec_input_name = rec
+            .inputs
+            .first()
+            .map(|i| i.name.clone())
+            .context("rec model has no inputs")?;
+
+        Ok(Self {
+            det: Mutex::new(det),
+            rec: Mutex::new(rec),
+            det_input_name,
+            rec_input_name,
+            dict,
+            engine_version,
+            score_thresh,
+            unclip_ratio,
+            max_boxes,
+            max_pixels: max_pixels.clamp(256, 4096),
+        })
+    }
+
+}
+
+impl OcrEngine for OnnxPaddleOcr {
+    fn engine_name(&self) -> &'static str {
+        PADDLE_ONNX_ENGINE
+    }
+
+    fn engine_version(&self) -> String {
+        self.engine_version.clone()
+    }
+
+    // The trait method's elided lifetime ties the return to `&self`; the body
+    // returns a literal, but the signature must match the trait, so allow the
+    // `'static`-narrowing lint here.
+    #[allow(clippy::unnecessary_literal_bound)]
+    fn model(&self) -> &str {
+        // Static label for the progress display; the per-asset hash lives
+        // in `engine_version`.
+        "ppocrv5-mobile-kor"
+    }
+
+    fn recognize(&self, image_bytes: &[u8], _lang_hint: Option<&Lang>) -> Result<OcrText> {
+        let img = image::load_from_memory(image_bytes)
+            .context("decoding image for OCR")?
+            .to_rgb8();
+        let (orig_w, orig_h) = (img.width(), img.height());
+        if orig_w == 0 || orig_h == 0 {
+            return Ok(empty_ocr(self));
+        }
+
+        // ── det ────────────────────────────────────────────────────────
+        let (det_w, det_h) = det_target_dims(orig_w, orig_h, self.max_pixels);
+        let det_img = image::imageops::resize(
+            &img,
+            det_w,
+            det_h,
+            image::imageops::FilterType::Triangle,
+        );
+        let prob = self.run_det(&det_img)?; // (det_h, det_w) prob map
+        let scale_x = orig_w as f32 / det_w as f32;
+        let scale_y = orig_h as f32 / det_h as f32;
+        let mut boxes = det_postprocess(
+            &prob,
+            prob.w,
+            prob.h,
+            self.score_thresh,
+            self.unclip_ratio,
+        );
+        if boxes.len() > self.max_boxes {
+            tracing::warn!(
+                target: "kebab-parse-image",
+                "paddle-onnx: {} boxes exceeds max_boxes {} — truncating",
+                boxes.len(),
+                self.max_boxes
+            );
+            boxes.truncate(self.max_boxes);
+        }
+        // scale box corners back to original image coordinates
+        for b in &mut boxes {
+            for p in &mut b.corners {
+                p.0 *= scale_x;
+                p.1 *= scale_y;
+            }
+        }
+
+        if boxes.is_empty() {
+            return Ok(empty_ocr(self));
+        }
+
+        // ── rec per box (reading order: top→bottom, left→right) ─────────
+        boxes.sort_by(|a, b| {
+            let ay = a.center_y();
+            let by = b.center_y();
+            // group into rough rows by 0.5*box height tolerance via y then x
+            ay.partial_cmp(&by)
+                .unwrap_or(std::cmp::Ordering::Equal)
+                .then_with(|| {
+                    a.center_x()
+                        .partial_cmp(&b.center_x())
+                        .unwrap_or(std::cmp::Ordering::Equal)
+                })
+        });
+
+        let mut regions: Vec<OcrRegion> = Vec::with_capacity(boxes.len());
+        for b in &boxes {
+            let crop = rectify_crop(&img, &b.corners);
+            if crop.width() == 0 || crop.height() == 0 {
+                continue;
+            }
+            let (text, conf) = self.run_rec(&crop)?;
+            if text.is_empty() {
+                continue; // rec empty → skip this box, keep the rest
+            }
+            let (x, y, w, h) = b.aabb();
+            regions.push(OcrRegion {
+                bbox: (x, y, w, h),
+                text,
+                confidence: conf,
+            });
+        }
+
+        let joined = regions
+            .iter()
+            .map(|r| r.text.as_str())
+            .collect::<Vec<_>>()
+            .join("\n");
+
+        Ok(OcrText {
+            joined,
+            regions,
+            engine: PADDLE_ONNX_ENGINE.to_string(),
+            engine_version: self.engine_version.clone(),
+        })
+    }
+}
+
+impl OnnxPaddleOcr {
+    /// Run det session → `(det_h, det_w)` probability map as a row-major Vec.
+    fn run_det(&self, det_img: &image::RgbImage) -> Result<ProbMap> {
+        let (w, h) = (det_img.width() as usize, det_img.height() as usize);
+        let mut arr = Array4::<f32>::zeros((1, 3, h, w));
+        for (x, y, px) in det_img.enumerate_pixels() {
+            let (xi, yi) = (x as usize, y as usize);
+            for c in 0..3 {
+                let v = f32::from(px[c]) / 255.0;
+                arr[[0, c, yi, xi]] = (v - IMAGENET_MEAN[c]) / IMAGENET_STD[c];
+            }
+        }
+        let input = Value::from_array(arr).context("det Value::from_array")?;
+        let sess = self.det.lock().unwrap_or_else(std::sync::PoisonError::into_inner);
+        let outputs = sess
+            .run(ort::inputs![self.det_input_name.as_str() => input]?)
+            .context("det session run")?;
+        let out_name = sess.outputs[0].name.clone();
+        let view = outputs[out_name.as_str()]
+            .try_extract_tensor::<f32>()
+            .context("det output extract")?;
+        // shape [1,1,H,W]
+        let shape = view.shape();
+        let (oh, ow) = (shape[shape.len() - 2], shape[shape.len() - 1]);
+        let data: Vec<f32> = view.iter().copied().collect();
+        Ok(ProbMap { w: ow, h: oh, data })
+    }
+
+    /// Run rec session on a rectified crop → (decoded string, mean confidence).
+    fn run_rec(&self, crop: &image::RgbImage) -> Result<(String, f32)> {
+        // resize keep-aspect to height 48, then this single crop is its own batch
+        let (cw, ch) = (crop.width().max(1), crop.height().max(1));
+        let new_w = ((REC_HEIGHT as f32 / ch as f32) * cw as f32).round().max(1.0) as u32;
+        let resized = image::imageops::resize(
+            crop,
+            new_w,
+            REC_HEIGHT,
+            image::imageops::FilterType::Triangle,
+        );
+        let w = new_w as usize;
+        let h = REC_HEIGHT as usize;
+        let mut arr = Array4::<f32>::zeros((1, 3, h, w));
+        for (x, y, px) in resized.enumerate_pixels() {
+            let (xi, yi) = (x as usize, y as usize);
+            for c in 0..3 {
+                let v = f32::from(px[c]) / 255.0;
+                arr[[0, c, yi, xi]] = (v - 0.5) / 0.5; // [-1, 1]
+            }
+        }
+        let input = Value::from_array(arr).context("rec Value::from_array")?;
+        let sess = self.rec.lock().unwrap_or_else(std::sync::PoisonError::into_inner);
+        let outputs = sess
+            .run(ort::inputs![self.rec_input_name.as_str() => input]?)
+            .context("rec session run")?;
+        let out_name = sess.outputs[0].name.clone();
+        let view = outputs[out_name.as_str()]
+            .try_extract_tensor::<f32>()
+            .context("rec output extract")?;
+        // shape [1, T, C]
+        let shape = view.shape();
+        let (t, c) = (shape[shape.len() - 2], shape[shape.len() - 1]);
+        if c != REC_CLASSES {
+            anyhow::bail!(
+                "rec output has {c} classes, expected {REC_CLASSES} \
+                 (dict {DICT_LINES} + blank + space)"
+            );
+        }
+        let data: Vec<f32> = view.iter().copied().collect();
+        Ok(self.ctc_greedy_decode(&data, t, c))
+    }
+
+    /// CTC greedy decode over `[T, C]` logits/probs (row-major). Delegates to
+    /// [`ctc_greedy_decode_with_dict`] so the algorithm is testable without
+    /// loading ONNX sessions (see `tests::ctc_greedy_decode_golden`).
+    fn ctc_greedy_decode(&self, data: &[f32], t: usize, c: usize) -> (String, f32) {
+        ctc_greedy_decode_with_dict(data, t, c, &self.dict)
+    }
+}
+
+/// CTC greedy decode: per-timestep argmax → collapse consecutive duplicates →
+/// drop blank (index 0) → map class index to string via `dict`.
+/// Pure Rust, no I/O — usable in unit tests without loading ONNX sessions.
+fn ctc_greedy_decode_with_dict(data: &[f32], t: usize, c: usize, dict: &[String]) -> (String, f32) {
+    let class_to_str = |idx: usize| -> Option<&str> {
+        match idx {
+            CTC_BLANK => None,
+            CTC_SPACE => Some(" "),
+            i if (1..=DICT_LINES).contains(&i) => Some(dict[i - 1].as_str()),
+            _ => None,
+        }
+    };
+    let mut out = String::new();
+    let mut confs: Vec<f32> = Vec::new();
+    let mut prev = usize::MAX;
+    for ti in 0..t {
+        let row = &data[ti * c..(ti + 1) * c];
+        let mut best = 0usize;
+        let mut best_v = f32::MIN;
+        for (i, &v) in row.iter().enumerate() {
+            if v > best_v {
+                best_v = v;
+                best = i;
+            }
+        }
+        if best != prev && best != CTC_BLANK {
+            if let Some(s) = class_to_str(best) {
+                out.push_str(s);
+                confs.push(best_v);
+            }
+        }
+        prev = best;
+    }
+    let conf = if confs.is_empty() {
+        0.0
+    } else {
+        confs.iter().sum::<f32>() / confs.len() as f32
+    };
+    (out, conf)
+}
+
+fn empty_ocr(e: &OnnxPaddleOcr) -> OcrText {
+    OcrText {
+        joined: String::new(),
+        regions: Vec::new(),
+        engine: PADDLE_ONNX_ENGINE.to_string(),
+        engine_version: e.engine_version.clone(),
+    }
+}
+
+/// Load the dict file: one token per line, trailing newline tolerated.
+/// Empty lines are preserved as empty tokens (PaddleOCR dicts may carry a
+/// blank-looking line; index integrity matters more than trimming).
+fn load_dict(path: &Path) -> Result<Vec<String>> {
+    let raw = std::fs::read_to_string(path)?;
+    // split on '\n'; drop a single trailing empty element from the final newline
+    let mut lines: Vec<String> = raw.split('\n').map(|s| s.trim_end_matches('\r').to_string()).collect();
+    if lines.last().is_some_and(String::is_empty) {
+        lines.pop();
+    }
+    Ok(lines)
+}
+
+/// Resolve the paddle-onnx `engine_version` for `config` without loading the
+/// ONNX sessions (T9). This is the same blake3-over-assets string that a
+/// constructed [`OnnxPaddleOcr`] exposes via [`OcrEngine::engine_version`], so
+/// the ingest config signature can include it. Reads ~17 MB of model bytes —
+/// callers MUST memoize per (det,rec,dict) triple (m3: never re-hash per asset).
+pub fn engine_version_for_config(config: &kebab_config::Config) -> Result<String> {
+    compute_engine_version(&ModelPaths::from_config(config))
+}
+
+/// blake3 over det + rec + dict bytes → stable `engine_version`.
+fn compute_engine_version(paths: &ModelPaths) -> Result<String> {
+    let mut hasher = blake3::Hasher::new();
+    for p in [&paths.det, &paths.rec, &paths.dict] {
+        let bytes = std::fs::read(p).with_context(|| format!("reading {}", p.display()))?;
+        hasher.update(&bytes);
+    }
+    let hash = hasher.finalize();
+    let hex = hash.to_hex();
+    Ok(format!("ppocrv5-mobile-kor-{}", &hex.as_str()[..12]))
+}
+
+/// det resize target: keep aspect, cap long edge at `min(max_pixels, 960)`,
+/// then round each dim to a multiple of 32 (DBNet stride). Reproduces the T0a
+/// golden (192×900 → 192×896).
+fn det_target_dims(w: u32, h: u32, max_pixels: u32) -> (u32, u32) {
+    let limit = DET_LIMIT_SIDE_LEN.min(max_pixels.max(32));
+    let long = w.max(h);
+    let ratio = if long > limit {
+        limit as f32 / long as f32
+    } else {
+        1.0
+    };
+    let rw = (w as f32 * ratio).round().max(1.0);
+    let rh = (h as f32 * ratio).round().max(1.0);
+    let round32 = |v: f32| -> u32 {
+        let r = (v / 32.0).round() as u32 * 32;
+        r.max(32)
+    };
+    (round32(rw), round32(rh))
+}
+
+// ── det postprocessing ──────────────────────────────────────────────────────
+
+struct ProbMap {
+    w: usize,
+    h: usize,
+    data: Vec<f32>,
+}
+
+impl ProbMap {
+    #[inline]
+    fn at(&self, x: usize, y: usize) -> f32 {
+        self.data[y * self.w + x]
+    }
+}
+
+/// A detected text box: 4 corners (clockwise from top-left) in det-image
+/// coordinates (later scaled to original).
+#[derive(Clone, Debug)]
+struct DetBox {
+    corners: [(f32, f32); 4],
+}
+
+impl DetBox {
+    fn center_x(&self) -> f32 {
+        self.corners.iter().map(|p| p.0).sum::<f32>() / 4.0
+    }
+    fn center_y(&self) -> f32 {
+        self.corners.iter().map(|p| p.1).sum::<f32>() / 4.0
+    }
+    /// Axis-aligned bounding box (x, y, w, h) clamped to non-negative.
+    fn aabb(&self) -> (u32, u32, u32, u32) {
+        let xs = self.corners.iter().map(|p| p.0);
+        let ys = self.corners.iter().map(|p| p.1);
+        let minx = xs.clone().fold(f32::MAX, f32::min).max(0.0);
+        let maxx = xs.fold(f32::MIN, f32::max).max(0.0);
+        let miny = ys.clone().fold(f32::MAX, f32::min).max(0.0);
+        let maxy = ys.fold(f32::MIN, f32::max).max(0.0);
+        (
+            minx.round() as u32,
+            miny.round() as u32,
+            (maxx - minx).round().max(0.0) as u32,
+            (maxy - miny).round().max(0.0) as u32,
+        )
+    }
+}
+
+/// DBNet-style postprocess: threshold → connected components → contour →
+/// min-area rect (rotating calipers) → box-score filter → unclip → boxes.
+/// Pinned by `tests/golden/det_boxes_clean_paragraph.json` (3 boxes).
+fn det_postprocess(
+    prob: &ProbMap,
+    w: usize,
+    h: usize,
+    score_thresh: f32,
+    unclip_ratio: f32,
+) -> Vec<DetBox> {
+    use image::{GrayImage, Luma};
+
+    // binarize at the detection threshold
+    let mut bin = GrayImage::new(w as u32, h as u32);
+    for y in 0..h {
+        for x in 0..w {
+            let v = if prob.at(x, y) > DET_BIN_THRESH { 255u8 } else { 0u8 };
+            bin.put_pixel(x as u32, y as u32, Luma([v]));
+        }
+    }
+
+    let contours = imageproc::contours::find_contours::<u32>(&bin);
+    let mut boxes = Vec::new();
+    for contour in &contours {
+        if contour.points.len() < 4 {
+            continue;
+        }
+        let pts: Vec<(f32, f32)> = contour
+            .points
+            .iter()
+            .map(|p| (p.x as f32, p.y as f32))
+            .collect();
+        let Some(rect) = min_area_rect(&pts) else {
+            continue;
+        };
+        // mean-prob box score over the AABB of the rotated rect
+        let score = box_score(prob, &rect.corners);
+        if score < score_thresh {
+            continue;
+        }
+        let unclipped = unclip_rect(&rect, unclip_ratio);
+        boxes.push(DetBox { corners: unclipped });
+    }
+    boxes
+}
+
+/// Mean probability inside the axis-aligned bbox of the rect — the
+/// `box_thresh` mean-prob filter used by the golden harness.
+fn box_score(prob: &ProbMap, corners: &[(f32, f32); 4]) -> f32 {
+    let minx = corners.iter().map(|p| p.0).fold(f32::MAX, f32::min).max(0.0) as usize;
+    let maxx = (corners.iter().map(|p| p.0).fold(f32::MIN, f32::max).max(0.0) as usize)
+        .min(prob.w.saturating_sub(1));
+    let miny = corners.iter().map(|p| p.1).fold(f32::MAX, f32::min).max(0.0) as usize;
+    let maxy = (corners.iter().map(|p| p.1).fold(f32::MIN, f32::max).max(0.0) as usize)
+        .min(prob.h.saturating_sub(1));
+    if maxx <= minx || maxy <= miny {
+        return 0.0;
+    }
+    let mut sum = 0.0f32;
+    let mut n = 0usize;
+    for y in miny..=maxy {
+        for x in minx..=maxx {
+            sum += prob.at(x, y);
+            n += 1;
+        }
+    }
+    if n == 0 { 0.0 } else { sum / n as f32 }
+}
+
+/// Rotated rect described by its 4 corners + box dims.
+#[derive(Clone, Debug)]
+struct RotRect {
+    corners: [(f32, f32); 4],
+    width: f32,
+    height: f32,
+}
+
+/// Minimum-area enclosing rectangle of a point set via rotating calipers on
+/// the convex hull (pure Rust — no OpenCV / clipper2).
+fn min_area_rect(points: &[(f32, f32)]) -> Option<RotRect> {
+    let hull = convex_hull(points);
+    if hull.len() < 3 {
+        return None;
+    }
+    let n = hull.len();
+    let mut best_area = f32::MAX;
+    let mut best: Option<RotRect> = None;
+    for i in 0..n {
+        let p0 = hull[i];
+        let p1 = hull[(i + 1) % n];
+        let edge = (p1.0 - p0.0, p1.1 - p0.1);
+        let len = (edge.0 * edge.0 + edge.1 * edge.1).sqrt();
+        if len < 1e-6 {
+            continue;
+        }
+        let ux = (edge.0 / len, edge.1 / len); // edge direction
+        let uy = (-ux.1, ux.0); // normal
+        let (mut min_u, mut max_u) = (f32::MAX, f32::MIN);
+        let (mut min_v, mut max_v) = (f32::MAX, f32::MIN);
+        for &p in &hull {
+            let du = p.0 * ux.0 + p.1 * ux.1;
+            let dv = p.0 * uy.0 + p.1 * uy.1;
+            min_u = min_u.min(du);
+            max_u = max_u.max(du);
+            min_v = min_v.min(dv);
+            max_v = max_v.max(dv);
+        }
+        let area = (max_u - min_u) * (max_v - min_v);
+        if area < best_area {
+            best_area = area;
+            // reconstruct corners in (u,v) basis → world
+            let to_world = |u: f32, v: f32| (u * ux.0 + v * uy.0, u * ux.1 + v * uy.1);
+            let corners = [
+                to_world(min_u, min_v),
+                to_world(max_u, min_v),
+                to_world(max_u, max_v),
+                to_world(min_u, max_v),
+            ];
+            best = Some(RotRect {
+                corners,
+                width: max_u - min_u,
+                height: max_v - min_v,
+            });
+        }
+    }
+    best
+}
+
+/// Andrew's monotone chain convex hull. Returns CCW hull without duplicates.
+fn convex_hull(points: &[(f32, f32)]) -> Vec<(f32, f32)> {
+    let mut pts: Vec<(f32, f32)> = points.to_vec();
+    pts.sort_by(|a, b| {
+        a.0.partial_cmp(&b.0)
+            .unwrap_or(std::cmp::Ordering::Equal)
+            .then(a.1.partial_cmp(&b.1).unwrap_or(std::cmp::Ordering::Equal))
+    });
+    pts.dedup();
+    if pts.len() < 3 {
+        return pts;
+    }
+    let cross = |o: (f32, f32), a: (f32, f32), b: (f32, f32)| {
+        (a.0 - o.0) * (b.1 - o.1) - (a.1 - o.1) * (b.0 - o.0)
+    };
+    let mut lower: Vec<(f32, f32)> = Vec::new();
+    for &p in &pts {
+        while lower.len() >= 2 && cross(lower[lower.len() - 2], lower[lower.len() - 1], p) <= 0.0 {
+            lower.pop();
+        }
+        lower.push(p);
+    }
+    let mut upper: Vec<(f32, f32)> = Vec::new();
+    for &p in pts.iter().rev() {
+        while upper.len() >= 2 && cross(upper[upper.len() - 2], upper[upper.len() - 1], p) <= 0.0 {
+            upper.pop();
+        }
+        upper.push(p);
+    }
+    lower.pop();
+    upper.pop();
+    lower.extend(upper);
+    lower
+}
+
+/// Unclip a rotated rect by `ratio` (PaddleOCR `distance = area*ratio/perimeter`),
+/// expanding width + height by `2*distance`. For a rectangle this matches the
+/// general polygon offset PaddleOCR uses (pyclipper) — pure Rust here.
+fn unclip_rect(rect: &RotRect, ratio: f32) -> [(f32, f32); 4] {
+    let area = rect.width * rect.height;
+    let perimeter = 2.0 * (rect.width + rect.height);
+    if perimeter < 1e-6 {
+        return rect.corners;
+    }
+    let distance = area * ratio / perimeter;
+    // Offset every EDGE outward by `distance` (PaddleOCR pyclipper polygon
+    // offset): width and height each grow by 2*distance. A naive radial
+    // push-from-centroid is WRONG for text boxes — a wide/short box has an
+    // almost-horizontal diagonal, so radial expansion barely grows the height
+    // and clips character tops/bottoms (ㄷ→ㄴ, ascenders lost). We instead
+    // expand along the rect's own (u, v) axes recovered from its ordered
+    // corners (c0=min_u,min_v; c1=max_u,min_v; c2=max_u,max_v; c3=min_u,max_v).
+    let c = &rect.corners;
+    let unit = |dx: f32, dy: f32| -> (f32, f32) {
+        let len = (dx * dx + dy * dy).sqrt();
+        if len > 1e-6 { (dx / len, dy / len) } else { (0.0, 0.0) }
+    };
+    let u = unit(c[1].0 - c[0].0, c[1].1 - c[0].1); // +u (along width)
+    let v = unit(c[3].0 - c[0].0, c[3].1 - c[0].1); // +v (along height)
+    let off = |p: (f32, f32), su: f32, sv: f32| -> (f32, f32) {
+        (
+            p.0 + su * distance * u.0 + sv * distance * v.0,
+            p.1 + su * distance * u.1 + sv * distance * v.1,
+        )
+    };
+    [
+        off(c[0], -1.0, -1.0),
+        off(c[1], 1.0, -1.0),
+        off(c[2], 1.0, 1.0),
+        off(c[3], -1.0, 1.0),
+    ]
+}
+
+// ── crop + rectify ───────────────────────────────────────────────────────────
+
+/// Perspective-warp the quadrilateral `corners` (clockwise from top-left) into
+/// a horizontal strip. Output size derives from the box edge lengths.
+fn rectify_crop(img: &image::RgbImage, corners: &[(f32, f32); 4]) -> image::RgbImage {
+    // order corners: top-left, top-right, bottom-right, bottom-left
+    let ordered = order_corners(corners);
+    let dist = |a: (f32, f32), b: (f32, f32)| ((a.0 - b.0).powi(2) + (a.1 - b.1).powi(2)).sqrt();
+    let w = dist(ordered[0], ordered[1]).max(dist(ordered[3], ordered[2]));
+    let h = dist(ordered[0], ordered[3]).max(dist(ordered[1], ordered[2]));
+    let out_w = w.round().max(1.0) as u32;
+    let out_h = h.round().max(1.0) as u32;
+    let mut out = image::RgbImage::new(out_w, out_h);
+    let (iw, ih) = (img.width() as f32, img.height() as f32);
+    // bilinear map from output grid back to the source quad (inverse via
+    // bilinear interpolation of the four corners — adequate for near-affine
+    // text boxes).
+    for oy in 0..out_h {
+        let fy = oy as f32 / (out_h.max(1) as f32 - 1.0).max(1.0);
+        for ox in 0..out_w {
+            let fx = ox as f32 / (out_w.max(1) as f32 - 1.0).max(1.0);
+            // bilinear blend of the four source corners
+            let top = (
+                ordered[0].0 + (ordered[1].0 - ordered[0].0) * fx,
+                ordered[0].1 + (ordered[1].1 - ordered[0].1) * fx,
+            );
+            let bot = (
+                ordered[3].0 + (ordered[2].0 - ordered[3].0) * fx,
+                ordered[3].1 + (ordered[2].1 - ordered[3].1) * fx,
+            );
+            let sx = (top.0 + (bot.0 - top.0) * fy).clamp(0.0, iw - 1.0);
+            let sy = (top.1 + (bot.1 - top.1) * fy).clamp(0.0, ih - 1.0);
+            let px = img.get_pixel(sx.round() as u32, sy.round() as u32);
+            out.put_pixel(ox, oy, *px);
+        }
+    }
+    out
+}
+
+/// Order 4 corners as [top-left, top-right, bottom-right, bottom-left] using
+/// coordinate sums/diffs (standard PaddleOCR ordering).
+fn order_corners(corners: &[(f32, f32); 4]) -> [(f32, f32); 4] {
+    // top-left has smallest x+y, bottom-right largest x+y;
+    // top-right smallest y-x, bottom-left largest y-x.
+    let mut tl = corners[0];
+    let mut br = corners[0];
+    let mut tr = corners[0];
+    let mut bl = corners[0];
+    let (mut min_sum, mut max_sum) = (f32::MAX, f32::MIN);
+    let (mut min_diff, mut max_diff) = (f32::MAX, f32::MIN);
+    for &p in corners {
+        let sum = p.0 + p.1;
+        let diff = p.1 - p.0;
+        if sum < min_sum {
+            min_sum = sum;
+            tl = p;
+        }
+        if sum > max_sum {
+            max_sum = sum;
+            br = p;
+        }
+        if diff < min_diff {
+            min_diff = diff;
+            tr = p;
+        }
+        if diff > max_diff {
+            max_diff = diff;
+            bl = p;
+        }
+    }
+    [tl, tr, br, bl]
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn det_target_dims_matches_golden() {
+        // T0a golden: clean_paragraph 192×900 → det input 192×896.
+        assert_eq!(det_target_dims(900, 192, 1600), (896, 192));
+    }
+
+    #[test]
+    fn convex_hull_square() {
+        let pts = vec![(0.0, 0.0), (10.0, 0.0), (10.0, 10.0), (0.0, 10.0), (5.0, 5.0)];
+        let hull = convex_hull(&pts);
+        assert_eq!(hull.len(), 4);
+    }
+
+    #[test]
+    fn min_area_rect_axis_aligned() {
+        let pts = vec![(0.0, 0.0), (20.0, 0.0), (20.0, 5.0), (0.0, 5.0)];
+        let r = min_area_rect(&pts).expect("rect");
+        let (lo, hi) = (r.width.min(r.height), r.width.max(r.height));
+        assert!((lo - 5.0).abs() < 1e-3, "short side {lo}");
+        assert!((hi - 20.0).abs() < 1e-3, "long side {hi}");
+    }
+
+    #[test]
+    fn dict_length_mismatch_is_construction_error() {
+        // T10: a dict whose line count != DICT_LINES must fail at construction
+        // (before loading the ONNX sessions) rather than mis-decoding silently.
+        use std::io::Write;
+        let dir = tempfile::tempdir().unwrap();
+        let dict_path = dir.path().join("bad_dict.txt");
+        let mut f = std::fs::File::create(&dict_path).unwrap();
+        writeln!(f, "a\nb\nc").unwrap(); // 3 lines, not DICT_LINES
+        let paths = ModelPaths {
+            det: dir.path().join("unused_det.onnx"),
+            rec: dir.path().join("unused_rec.onnx"),
+            dict: dict_path,
+        };
+        let err = OnnxPaddleOcr::from_paths(&paths, 0.3, 1.5, 1000, 1600)
+            .expect_err("dict mismatch must error");
+        let msg = format!("{err:#}");
+        assert!(msg.contains("dict has 3 lines"), "unexpected error: {msg}");
+    }
+
+    #[test]
+    fn model_paths_from_config_uses_overrides() {
+        // T7: unset overrides → bundled default asset paths.
+        let mut cfg = kebab_config::Config::defaults();
+        let def = ModelPaths::from_config(&cfg);
+        assert!(def.det.ends_with("ppocrv5_mobile_det.onnx"), "{:?}", def.det);
+        assert!(def.rec.ends_with("korean_ppocrv5_mobile_rec.onnx"), "{:?}", def.rec);
+        assert!(def.dict.ends_with("korean_dict.txt"), "{:?}", def.dict);
+
+        // Override det + dict; rec stays bundled (partial override allowed).
+        cfg.image.ocr.det_model = Some("/custom/det.onnx".to_string());
+        cfg.image.ocr.dict = Some("/custom/dict.txt".to_string());
+        let ov = ModelPaths::from_config(&cfg);
+        assert_eq!(ov.det, PathBuf::from("/custom/det.onnx"));
+        assert_eq!(ov.dict, PathBuf::from("/custom/dict.txt"));
+        assert!(ov.rec.ends_with("korean_ppocrv5_mobile_rec.onnx"), "{:?}", ov.rec);
+    }
+
+    #[test]
+    fn unclip_expands_box() {
+        let rect = RotRect {
+            corners: [(0.0, 0.0), (20.0, 0.0), (20.0, 5.0), (0.0, 5.0)],
+            width: 20.0,
+            height: 5.0,
+        };
+        let out = unclip_rect(&rect, 1.5);
+        // unclipped box must be strictly larger than the original
+        let orig_minx = 0.0;
+        let new_minx = out.iter().map(|p| p.0).fold(f32::MAX, f32::min);
+        assert!(new_minx < orig_minx, "expected expansion, got {new_minx}");
+    }
+
+    /// Golden pin: verify `ctc_greedy_decode_with_dict` against pre-recorded
+    /// argmax sequences in `tests/golden/ctc_rec_golden.json`. No ONNX sessions
+    /// needed — only the bundled dict is loaded.
+    #[test]
+    fn ctc_greedy_decode_golden() {
+        let json_str = include_str!("../tests/golden/ctc_rec_golden.json");
+        let golden: serde_json::Value = serde_json::from_str(json_str).unwrap();
+        let dict_path = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
+            .join("assets/paddleocr-onnx/korean_dict.txt");
+        let dict = load_dict(&dict_path).expect("bundled dict must load");
+
+        for case in golden["rec_cases"].as_array().unwrap() {
+            let t = case["T"].as_u64().unwrap() as usize;
+            let c = case["C"].as_u64().unwrap() as usize;
+            let argmax_idx: Vec<usize> = case["argmax_idx"]
+                .as_array()
+                .unwrap()
+                .iter()
+                .map(|v| v.as_u64().unwrap() as usize)
+                .collect();
+            let expected = case["decoded"].as_str().unwrap();
+            // build one-hot logits: timestep t fires class argmax_idx[t] = 1.0
+            let mut data = vec![0.0f32; t * c];
+            for (ti, &idx) in argmax_idx.iter().enumerate() {
+                data[ti * c + idx] = 1.0;
+            }
+            let (decoded, _conf) = ctc_greedy_decode_with_dict(&data, t, c, &dict);
+            assert_eq!(
+                decoded, expected,
+                "CTC decode mismatch for text={:?}",
+                case["text"]
+            );
+        }
+    }
+
+    /// Golden pin: verify `box_score` and `unclip_rect` against corner data
+    /// from `tests/golden/det_boxes_clean_paragraph.json`. No ONNX needed.
+    #[test]
+    fn det_box_score_golden() {
+        let json_str = include_str!("../tests/golden/det_boxes_clean_paragraph.json");
+        let golden: serde_json::Value = serde_json::from_str(json_str).unwrap();
+
+        let hw = golden["det_input_hw"].as_array().unwrap();
+        let h = hw[0].as_u64().unwrap() as usize;
+        let w = hw[1].as_u64().unwrap() as usize;
+        let thresh = golden["thresh"].as_f64().unwrap() as f32;
+        let unclip_ratio = golden["unclip_ratio"].as_f64().unwrap() as f32;
+
+        // uniform prob map at 0.9 — all boxes must score above det thresh
+        let prob = ProbMap { w, h, data: vec![0.9f32; w * h] };
+
+        for box_entry in golden["boxes"].as_array().unwrap() {
+            let poly = box_entry["poly"].as_array().unwrap();
+            let corners: [(f32, f32); 4] = [
+                (poly[0][0].as_f64().unwrap() as f32, poly[0][1].as_f64().unwrap() as f32),
+                (poly[1][0].as_f64().unwrap() as f32, poly[1][1].as_f64().unwrap() as f32),
+                (poly[2][0].as_f64().unwrap() as f32, poly[2][1].as_f64().unwrap() as f32),
+                (poly[3][0].as_f64().unwrap() as f32, poly[3][1].as_f64().unwrap() as f32),
+            ];
+            // box_score must be above det threshold
+            let score = box_score(&prob, &corners);
+            assert!(
+                score > thresh,
+                "box_score {score:.4} ≤ thresh {thresh} for poly {poly:?}"
+            );
+            // unclip_rect must expand the bounding box (min x strictly decreases)
+            let rect_w = (corners[1].0 - corners[0].0).abs().max(1.0);
+            let rect_h = (corners[3].1 - corners[0].1).abs().max(1.0);
+            let rot = RotRect { corners, width: rect_w, height: rect_h };
+            let expanded = unclip_rect(&rot, unclip_ratio);
+            let orig_min_x = corners.iter().map(|p| p.0).fold(f32::MAX, f32::min);
+            let exp_min_x = expanded.iter().map(|p| p.0).fold(f32::MAX, f32::min);
+            assert!(
+                exp_min_x < orig_min_x,
+                "unclip_rect must expand: orig_min_x={orig_min_x} exp_min_x={exp_min_x}"
+            );
+        }
+    }
+}
--- a/crates/kebab-parse-image/tests/golden/ctc_rec_golden.json
+++ b/crates/kebab-parse-image/tests/golden/ctc_rec_golden.json
@@ -0,0 +1,516 @@
+{
+  "dict_lines": 11945,
+  "rec_classes": 11947,
+  "blank_index": 0,
+  "space_index": 11946,
+  "mapping": "idx0=blank; idx 1..N=dict[idx-1]; idx N+1=space; classes=dict+2",
+  "rec_norm": "RGB, /255 then (x-0.5)/0.5 => [-1,1], height=48 keep-aspect pad",
+  "det_norm": "RGB, ImageNet mean/std *255 then /std, NCHW",
+  "rec_cases": [
+    {
+      "text": "RAG 시스템 검색 결과",
+      "decoded": "RAG시스템 검색 결과",
+      "cer": 0.0769,
+      "cer_nospace": 0.0,
+      "mapping_ok": true,
+      "T": 40,
+      "C": 11947,
+      "argmax_idx": [
+        0,
+        0,
+        11553,
+        0,
+        11536,
+        0,
+        0,
+        11542,
+        0,
+        0,
+        0,
+        6185,
+        0,
+        0,
+        6129,
+        0,
+        0,
+        9897,
+        0,
+        0,
+        11946,
+        0,
+        461,
+        0,
+        0,
+        0,
+        5654,
+        0,
+        11946,
+        0,
+        509,
+        0,
+        0,
+        0,
+        585,
+        0,
+        0,
+        0,
+        0,
+        0
+      ],
+      "collapsed_idx": [
+        11553,
+        11536,
+        11542,
+        6185,
+        6129,
+        9897,
+        11946,
+        461,
+        5654,
+        11946,
+        509,
+        585
+      ],
+      "collapsed_conf": [
+        0.0002,
+        0.0002,
+        0.0002,
+        0.0002,
+        0.0002,
+        0.0002,
+        0.0002,
+        0.0002,
+        0.0002,
+        0.0002,
+        0.0002,
+        0.0002
+      ],
+      "fired_timesteps": [
+        2,
+        4,
+        7,
+        11,
+        14,
+        17,
+        20,
+        22,
+        26,
+        28,
+        30,
+        34
+      ],
+      "fired_logit_top5": [
+        {
+          "t": 2,
+          "top5_idx": [
+            11553,
+            11583,
+            11551,
+            0,
+            11541
+          ],
+          "top5_val": [
+            0.9998,
+            0.0001,
+            0.0,
+            0.0,
+            0.0
+          ]
+        },
+        {
+          "t": 4,
+          "top5_idx": [
+            11536,
+            11566,
+            0,
+            11748,
+            11551
+          ],
+          "top5_val": [
+            0.9998,
+            0.0001,
+            0.0,
+            0.0,
+            0.0
+          ]
+        },
+        {
+          "t": 7,
+          "top5_idx": [
+            11542,
+            0,
+            11572,
+            11946,
+            11585
+          ],
+          "top5_val": [
+            0.9994,
+            0.0004,
+            0.0001,
+            0.0001,
+            0.0
+          ]
+        },
+        {
+          "t": 11,
+          "top5_idx": [
+            6185,
+            0,
+            11946,
+            7949,
+            11518
+          ],
+          "top5_val": [
+            0.9993,
+            0.0003,
+            0.0001,
+            0.0001,
+            0.0
+          ]
+        },
+        {
+          "t": 14,
+          "top5_idx": [
+            6129,
+            7893,
+            0,
+            9069,
+            11536
+          ],
+          "top5_val": [
+            0.9997,
+            0.0002,
+            0.0,
+            0.0,
+            0.0
+          ]
+        },
+        {
+          "t": 17,
+          "top5_idx": [
+            9897,
+            9882,
+            9889,
+            9785,
+            3429
+          ],
+          "top5_val": [
+            0.9999,
+            0.0,
+            0.0,
+            0.0,
+            0.0
+          ]
+        },
+        {
+          "t": 20,
+          "top5_idx": [
+            11946,
+            0,
+            11516,
+            11518,
+            11579
+          ],
+          "top5_val": [
+            0.9026,
+            0.0971,
+            0.0002,
+            0.0001,
+            0.0
+          ]
+        },
+        {
+          "t": 22,
+          "top5_idx": [
+            461,
+            462,
+            9281,
+            349,
+            0
+          ],
+          "top5_val": [
+            0.9995,
+            0.0003,
+            0.0001,
+            0.0,
+            0.0
+          ]
+        },
+        {
+          "t": 26,
+          "top5_idx": [
+            5654,
+            0,
+            5766,
+            8594,
+            6830
+          ],
+          "top5_val": [
+            1.0,
+            0.0,
+            0.0,
+            0.0,
+            0.0
+          ]
+        },
+        {
+          "t": 28,
+          "top5_idx": [
+            11946,
+            0,
+            11516,
+            11549,
+            11564
+          ],
+          "top5_val": [
+            0.9422,
+            0.0576,
+            0.0001,
+            0.0,
+            0.0
+          ]
+        },
+        {
+          "t": 30,
+          "top5_idx": [
+            509,
+            0,
+            453,
+            11946,
+            505
+          ],
+          "top5_val": [
+            0.9994,
+            0.0004,
+            0.0001,
+            0.0,
+            0.0
+          ]
+        },
+        {
+          "t": 34,
+          "top5_idx": [
+            585,
+            641,
+            0,
+            10329,
+            589
+          ],
+          "top5_val": [
+            0.9999,
+            0.0,
+            0.0,
+            0.0,
+            0.0
+          ]
+        }
+      ]
+    },
+    {
+      "text": "Embedding vector 0123",
+      "decoded": "Embedding vector 0123",
+      "cer": 0.0,
+      "cer_nospace": 0.0,
+      "mapping_ok": true,
+      "T": 41,
+      "C": 11947,
+      "argmax_idx": [
+        0,
+        11540,
+        0,
+        0,
+        11578,
+        0,
+        0,
+        11567,
+        0,
+        11570,
+        0,
+        11569,
+        0,
+        11569,
+        0,
+        11574,
+        0,
+        11579,
+        11572,
+        11572,
+        11946,
+        0,
+        11587,
+        11570,
+        0,
+        11568,
+        0,
+        11585,
+        11580,
+        0,
+        11583,
+        11946,
+        11946,
+        11520,
+        0,
+        11521,
+        0,
+        11522,
+        0,
+        11523,
+        0
+      ],
+      "collapsed_idx": [
+        11540,
+        11578,
+        11567,
+        11570,
+        11569,
+        11569,
+        11574,
+        11579,
+        11572,
+        11946,
+        11587,
+        11570,
+        11568,
+        11585,
+        11580,
+        11583,
+        11946,
+        11520,
+        11521,
+        11522,
+        11523
+      ],
+      "collapsed_conf": [
+        0.0002,
+        0.0002,
+        0.0002,
+        0.0002,
+        0.0002,
+        0.0002,
+        0.0002,
+        0.0002,
+        0.0001,
+        0.0002,
+        0.0002,
+        0.0002,
+        0.0002,
+        0.0002,
+        0.0002,
+        0.0002,
+        0.0002,
+        0.0002,
+        0.0002,
+        0.0002,
+        0.0002
+      ]
+    },
+    {
+      "text": "한글 OCR 정확도 테스트",
+      "decoded": "한글 OCR 정확도 테스트",
+      "cer": 0.0,
+      "cer_nospace": 0.0,
+      "mapping_ok": true,
+      "T": 41,
+      "C": 11947,
+      "argmax_idx": [
+        0,
+        0,
+        10921,
+        0,
+        0,
+        0,
+        845,
+        0,
+        11946,
+        0,
+        11550,
+        0,
+        0,
+        11538,
+        0,
+        11553,
+        0,
+        11946,
+        0,
+        7522,
+        0,
+        0,
+        11170,
+        0,
+        0,
+        0,
+        2321,
+        0,
+        11946,
+        11946,
+        9881,
+        0,
+        0,
+        0,
+        6129,
+        0,
+        0,
+        0,
+        10245,
+        0,
+        0
+      ],
+      "collapsed_idx": [
+        10921,
+        845,
+        11946,
+        11550,
+        11538,
+        11553,
+        11946,
+        7522,
+        11170,
+        2321,
+        11946,
+        9881,
+        6129,
+        10245
+      ],
+      "collapsed_conf": [
+        0.0002,
+        0.0002,
+        0.0002,
+        0.0002,
+        0.0002,
+        0.0002,
+        0.0002,
+        0.0002,
+        0.0002,
+        0.0002,
+        0.0002,
+        0.0002,
+        0.0002,
+        0.0002
+      ]
+    }
+  ],
+  "det_cases": [
+    {
+      "fixture": "clean_paragraph.png",
+      "orig_hw": [
+        192,
+        900
+      ],
+      "det_input_hw": [
+        192,
+        896
+      ],
+      "prob_shape": [
+        192,
+        896
+      ],
+      "prob_max": 1.0,
+      "prob_mean": 0.1139,
+      "positives_at_0.3": 19682,
+      "positive_frac": 0.1144,
+      "box_count": 3,
+      "postproc": "thresh=0.3 -> findContours -> minAreaRect -> unclip(ratio=1.5, area*r/peri); box_thresh=0.5 mean-prob filter; coords scaled back to orig hw"
+    }
+  ],
+  "blank_index_confirmed_by_gt": true
+}
--- a/crates/kebab-parse-image/tests/golden/det_boxes_clean_paragraph.json
+++ b/crates/kebab-parse-image/tests/golden/det_boxes_clean_paragraph.json
@@ -0,0 +1,78 @@
+{
+  "fixture": "clean_paragraph.png",
+  "orig_hw": [
+    192,
+    900
+  ],
+  "det_input_hw": [
+    192,
+    896
+  ],
+  "thresh": 0.3,
+  "unclip_ratio": 1.5,
+  "boxes": [
+    {
+      "poly": [
+        [
+          29,
+          135
+        ],
+        [
+          615,
+          134
+        ],
+        [
+          615,
+          149
+        ],
+        [
+          29,
+          150
+        ]
+      ],
+      "score": 0.8724
+    },
+    {
+      "poly": [
+        [
+          30,
+          92
+        ],
+        [
+          597,
+          92
+        ],
+        [
+          597,
+          105
+        ],
+        [
+          30,
+          105
+        ]
+      ],
+      "score": 0.9627
+    },
+    {
+      "poly": [
+        [
+          30,
+          47
+        ],
+        [
+          509,
+          47
+        ],
+        [
+          509,
+          60
+        ],
+        [
+          30,
+          60
+        ]
+      ],
+      "score": 0.9304
+    }
+  ]
+}
--- a/crates/kebab-parse-image/tests/paddle_e2e.rs
+++ b/crates/kebab-parse-image/tests/paddle_e2e.rs
@@ -0,0 +1,145 @@
+//! T11 e2e accuracy gate for the paddle-onnx OCR engine.
+//!
+//! Runs the full `OnnxPaddleOcr` pipeline (det → rectify → rec → CTC) over the
+//! synthetic OCR benchmark fixtures and asserts the mean character error rate
+//! (CER) over the clean text set is `<= 0.05`, matching the spec gate.
+//!
+//! Model assets come from `KEBAB_TEST_OCR_MODEL_DIR` (default: the crate's
+//! bundled `assets/paddleocr-onnx/`). Fixtures come from
+//! `KEBAB_TEST_OCR_FIXTURE_DIR` (default: the dogfood corpus). If either is
+//! absent the test skips with a warning rather than failing — CI without the
+//! large models / fixtures stays green (plan T0/M4).
+
+use std::collections::HashMap;
+use std::path::PathBuf;
+
+use kebab_parse_image::{ModelPaths, OcrEngine, OnnxPaddleOcr};
+
+/// Collapse all whitespace runs to a single space + trim — matches the Python
+/// `score_lib.norm` so the Rust gate and the bench harness agree.
+fn norm(s: &str) -> String {
+    s.split_whitespace().collect::<Vec<_>>().join(" ")
+}
+
+/// Character error rate = Levenshtein(gt, pred) / len(gt), both normalized.
+fn cer(gt: &str, pred: &str) -> f64 {
+    let g: Vec<char> = norm(gt).chars().collect();
+    let p: Vec<char> = norm(pred).chars().collect();
+    if g.is_empty() {
+        return if p.is_empty() { 0.0 } else { 1.0 };
+    }
+    let (m, n) = (g.len(), p.len());
+    let mut prev: Vec<usize> = (0..=n).collect();
+    for i in 1..=m {
+        let mut cur = vec![i; n + 1];
+        for j in 1..=n {
+            let cost = usize::from(g[i - 1] != p[j - 1]);
+            cur[j] = (prev[j] + 1).min(cur[j - 1] + 1).min(prev[j - 1] + cost);
+        }
+        prev = cur;
+    }
+    prev[n] as f64 / m as f64
+}
+
+fn fixture_dir() -> PathBuf {
+    std::env::var("KEBAB_TEST_OCR_FIXTURE_DIR").map_or_else(
+        |_| PathBuf::from("/build/dogfood/corpus/images/synthetic-ocr-bench"),
+        PathBuf::from,
+    )
+}
+
+/// T10: undecodable image bytes must surface as an error (the kebab-app caller
+/// then skips the asset + records provenance), not panic or return garbage.
+#[test]
+fn paddle_onnx_decode_failure_is_error() {
+    let paths = ModelPaths::from_default_dir();
+    if !paths.det.exists() || !paths.rec.exists() || !paths.dict.exists() {
+        eprintln!("SKIP paddle_onnx_decode_failure_is_error: model assets not found");
+        return;
+    }
+    let engine = OnnxPaddleOcr::from_paths(&paths, 0.3, 1.5, 1000, 1600).unwrap();
+    let err = engine
+        .recognize(b"not a real image", None)
+        .expect_err("garbage bytes must fail to decode");
+    let msg = format!("{err:#}");
+    assert!(msg.contains("decoding image"), "unexpected error: {msg}");
+}
+
+#[test]
+fn paddle_onnx_cer_gate() {
+    let paths = ModelPaths::from_default_dir();
+    if !paths.det.exists() || !paths.rec.exists() || !paths.dict.exists() {
+        eprintln!(
+            "SKIP paddle_onnx_cer_gate: model assets not found (det={}). \
+             Set KEBAB_TEST_OCR_MODEL_DIR or place assets/paddleocr-onnx/.",
+            paths.det.display()
+        );
+        return;
+    }
+    let fdir = fixture_dir();
+    let gt_path = fdir.join("gt.json");
+    if !gt_path.exists() {
+        eprintln!(
+            "SKIP paddle_onnx_cer_gate: fixtures not found at {}",
+            fdir.display()
+        );
+        return;
+    }
+
+    let gt: HashMap<String, String> =
+        serde_json::from_str(&std::fs::read_to_string(&gt_path).unwrap()).unwrap();
+
+    let engine = OnnxPaddleOcr::from_paths(&paths, 0.3, 1.5, 1000, 1600)
+        .expect("build OnnxPaddleOcr from bundled assets");
+
+    // "clean" set used for the gate — the standard, well-formed text fixtures.
+    // low_contrast / small_dense are intentionally hard and tracked but not
+    // part of the hard gate.
+    let gate_set = [
+        "clean_paragraph.png",
+        "title_body.png",
+        "tech_terms.png",
+        "korean_heavy.png",
+        "numbers_table.png",
+    ];
+
+    let mut gate_cers = Vec::new();
+    let mut names: Vec<&String> = gt.keys().collect();
+    names.sort();
+    println!("\n=== paddle-onnx CER per fixture ===");
+    for name in names {
+        let img_path = fdir.join(name);
+        if !img_path.exists() {
+            continue;
+        }
+        let bytes = std::fs::read(&img_path).unwrap();
+        let t0 = std::time::Instant::now();
+        let out = engine.recognize(&bytes, None).expect("recognize");
+        let dt = t0.elapsed();
+        let c = cer(&gt[name], &out.joined);
+        if std::env::var("KEBAB_OCR_DUMP").is_ok() {
+            println!("  GT  [{name}]: {:?}", norm(&gt[name]));
+            println!("  OUT [{name}]: {:?}", norm(&out.joined));
+        }
+        let gated = gate_set.contains(&name.as_str());
+        println!(
+            "{:<22} CER={:.4} {} ({} regions, {} ms)",
+            name,
+            c,
+            if gated { "[gate]" } else { "      " },
+            out.regions.len(),
+            dt.as_millis()
+        );
+        if gated {
+            gate_cers.push(c);
+        }
+    }
+
+    assert!(!gate_cers.is_empty(), "no gate fixtures were scored");
+    let mean = gate_cers.iter().sum::<f64>() / gate_cers.len() as f64;
+    println!("=== mean gate CER = {mean:.4} (threshold 0.05) ===\n");
+    assert!(
+        mean <= 0.05,
+        "paddle-onnx mean CER {mean:.4} exceeds 0.05 gate"
+    );
+}
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -20,7 +20,7 @@ Cargo workspace, 함수 호출 기반 모듈러 모놀리스. UI binary (`kebab-
 | 한국어 형태소분석 | `lindera-ko-dic` (FTS5 외부 tokenizer, v0.20.1) — 2자 이상 한국어 query 지원 |
 | LLM | Ollama HTTP (default `gemma4:e4b` ─ OCR / caption 와 family 통일. 사용자가 더 큰 variant `gemma4:26b` 등으로 override 가능) |
 | 음성 ASR | `whisper.cpp` (via `whisper-rs`) — P8 보류, 시스템 dep brainstorm 후 |
-| OCR (image) | Ollama vision LM (default `gemma4:e4b`) — `OcrEngine` trait 으로 Tesseract / Apple Vision 등 future swap (HOTFIXES P6-2) |
+| OCR (image) | `OcrEngine` trait, 2 백엔드: **`ollama-vision`** (default, `gemma4:e4b`) / **`paddle-onnx`** (v0.27.0 — PP-OCRv5 ONNX in-process via `ort` =2.0.0-rc.9, DBNet det + CTC rec, 후처리 min-area rect/unclip pure-Rust, Python 런타임 0). engine 선택은 `[image.ocr] engine`, 팩토리는 `kebab-app::build_image_ocr_engine`. e2e CER 0.005 / 큰 페이지 <4초. (HOTFIXES P6-2, 2026-06-04) |
 | OCR (PDF, v0.20.0+) | Ollama vision LM (default `qwen2.5vl:3b`) — post-extract enrichment via `kebab-app::pdf_ocr_apply` (H-1 resolution). DCTDecode-only v1 (FlateDecode/CCITTFax skip + warning). family asymmetry vs image OCR: PoC alnum 94.79% (qwen2.5vl) >> 27% (gemma4:e4b 받침), 본 단계에서 PDF OCR 만 qwen2.5vl. |
 | Image caption | Ollama vision LM, runtime gate `image.caption.enabled` (default OFF) |
 | RAG groundedness 검증 | `kebab-nli` 의 mDeBERTa-v3 XNLI 가 `(packed_chunks, generated_answer)` entailment 검사 (fb-41). `[rag] nli_threshold > 0` (default 0 = disabled, production 권장 0.5) 일 때 활성 — 미달 시 `refusal_reason = nli_verification_failed` (LLM self-judge ceiling 보완). 첫 호출 시 ~280 MB ONNX 자동 다운로드 |
@@ -212,7 +212,7 @@ kebab/
 │   ├── kebab-rag/                                     # RAG pipeline (P4-3)
 │   ├── kebab-nli/                                     # NLI verifier (mDeBERTa-v3 XNLI, fb-41 PR-9a/9b/9c-1)
 │   ├── kebab-eval/                                    # golden query runner + metrics (P5-1, P5-2)
-│   ├── kebab-parse-image/                             # ImageExtractor + Ollama OCR + caption (P6)
+│   ├── kebab-parse-image/                             # ImageExtractor + OCR (ollama-vision + paddle-onnx ONNX) + caption (P6)
 │   ├── kebab-parse-pdf/                               # lopdf per-page text extractor (P7-1)
 │   ├── kebab-parse-code/                              # tree-sitter AST extractors: Rust (P10-1A-2), Python + TypeScript + JavaScript (P10-1B), Go (P10-1C-Go), Java + Kotlin (P10-1C-JK — java.rs + kotlin.rs), C + C++ (P10-1D — c.rs + cpp.rs); chunker lives in kebab-chunk
 │   ├── kebab-app/                                     # facade (P0 시그니처 + P3-5/P6-4/P7-3 본체). src/derivation_payload.rs = 캐시 payload 인코딩 (v0.21.0)
--- a/docs/SMOKE.md
+++ b/docs/SMOKE.md
@@ -358,6 +358,24 @@ lang_hint = "kor"

 이미지 자산 한 장당 OCR 1 호출 + Caption 1 호출 → ~3-6초 (`gemma4:e4b` 기준). 다이어그램 / 카메라 사진 / 스크린샷 위주 워크스페이스에 권장. 책 / 스캔본은 P7 PDF 라인으로.

+**v0.27.0 — paddle-onnx 엔진 (오프라인, Ollama 불필요).** `[image.ocr] engine = "paddle-onnx"` 로 바꾸면 PP-OCRv5 ONNX 를 in-process 로 실행한다 (원격 vision LM 불필요, 큰 페이지 CPU <4초). embedding 까지 끄려면 `[models.embedding] provider = "none"` (lexical-only) 로 두면 Ollama 없이 OCR→FTS5 검색 전체 경로를 스모크할 수 있다:
+
+```toml
+[models.embedding]
+provider = "none"            # lexical-only — Ollama 불필요
+
+[image.ocr]
+enabled = true
+engine = "paddle-onnx"       # PP-OCRv5 ONNX in-process (Python/원격 0)
+model = "ppocrv5-mobile-kor"
+languages = ["kor", "eng"]
+max_pixels = 1600
+# det_model / rec_model / dict 로 번들 모델 경로 override 가능 (생략 시 번들 사용)
+# score_thresh = 0.3 / unclip_ratio = 1.5 / max_boxes = 1000 으로 검출 튜닝
+```
+
+스모크: `kebab ingest --config <cfg>` 후 `kebab search --config <cfg> --mode lexical "<이미지 안 한국어 단어>"` 가 그 image chunk 를 반환하면 OCR→FTS5 wiring 정상. engine 또는 모델을 바꾸면 다음 ingest 가 영향 이미지를 자동 재색인한다.
+
 ## P7-3 PDF ingestion

 `config.toml` 의 `[workspace] include` 에 `**/*.pdf` 를 추가하면 `kebab ingest` 가 텍스트 PDF 자산도 색인합니다. 외부 service 의존 없음 — `kebab-parse-pdf` 가 lopdf 로 페이지 단위 텍스트 추출, `kebab-chunk::PdfPageV1Chunker` 가 페이지 경계를 절대 넘지 않는 chunk 생성.
--- a/docs/superpowers/plans/2026-06-03-config-invalidation-plan.md
+++ b/docs/superpowers/plans/2026-06-03-config-invalidation-plan.md
@@ -0,0 +1,37 @@
+# Plan: ingest 설정 변경 자동 재색인 구현
+
+spec: `docs/superpowers/specs/2026-06-03-ocr-toggle-invalidation-spec.md`. 브랜치 `fix/ingest-config-invalidation`. 빌드 `CARGO_TARGET_DIR=/build/out/cargo-target`, **테스트 `-j 8`**(절대 `-j 1` 금지), cli 통합테스트용 `target` 심링크 후 정리.
+
+## Task 1 — ingest_config_signature 헬퍼 (kebab-app)
+- `fn ingest_config_signature(config: &Config, media: &MediaType) -> String` 추가.
+- 공통: `[chunking]` target_tokens, overlap_tokens, respect_markdown_headings, chunker_version.
+- image: + image.ocr.enabled (+model if enabled) + image.caption.enabled (+prompt_template_version if enabled).
+- pdf: + pdf.ocr.enabled (+model, always_on if enabled).
+- code: + ingest.code.{skip_generated_header, max_file_bytes, max_file_lines, extra_skip_globs(join), ast_chunk_max_lines, fallback_lines_per_chunk, fallback_lines_overlap}.
+- markdown: 공통만.
+- 결정적(필드 순서 고정). 단위테스트: 같은 config→같은 서명, 관련 필드 변경→서명 변경, 무관 필드(search 등)→불변.
+
+## Task 2 — 4개 ingest 경로에 composite parser_version 적용 (kebab-app/lib.rs)
+- md(~351), image(~1532), pdf(~2109), code 경로: `*_parser_version` = `ParserVersion(format!("{base}|{}", ingest_config_signature(config, media)))` (base = 각 extractor PARSER_VERSION).
+- 이 composite 를 (1) `try_skip_unchanged` 의 `current_parser_version` 으로 전달, (2) **persist 전 `canonical.parser_version` override** 로 저장. 두 곳 동일 보장.
+- doc_id 파생은 손대지 않음(workspace_path 조회).
+- markdown/code/image/pdf 각 경로에서 동일 패턴 적용 — 누락 없게.
+
+## Task 3 — 테스트
+- image.ocr off→on, caption off→on: 재색인(skip 아님). off→off / 동일 설정: skip 유지.
+- pdf.ocr off→on: 재색인. 동일: skip.
+- chunking target_tokens 변경: 전 타입 재색인. 무변경: skip.
+- ingest.code 변경: 코드 자산만 재색인.
+- **search/rag/ui 변경: 재색인 0** (회귀 가드).
+- 동일 config 재실행: 전 자산 skip (불필요 재색인 0).
+- 기존 skip 테스트(markdown unchanged 등) 회귀 0.
+
+## Task 4 — 검증 + 문서
+- `cargo clippy --workspace --all-targets -j 8 -- -D warnings` 0.
+- `cargo test -p kebab-app -p kebab-parse-image -p kebab-parse-pdf -p kebab-parse-code -p kebab-chunk -j 8` 통과(touched 크레이트 타깃; 전체 -j1 금지).
+- 스모크: 이미지 ocr off 색인 → config ocr on → `kebab ingest`(force 없이) → 그 이미지 재색인 확인.
+- tasks/HOTFIXES dated entry(일반화 + 업그레이드 1회 재색인 안내), Cargo.toml version **0.26.1 → 0.26.2**(+Cargo.lock), HANDOFF 1줄. README/wire 변화 없음.
+- 결과 요약 `/tmp/cfginval-result.md`(게이트 + 스모크 캡처).
+
+## 리뷰 루프
+완료 → 리더 clippy/타깃테스트(-j8) 독립 재확인 + 토글 스모크 → `gitea-pr`(title `fix(ingest): ingest 설정 변경 시 영향 자산 자동 재색인`) → 리뷰 루프 → 사용자 머지.
--- a/docs/superpowers/plans/2026-06-04-config-schema-reorg.md
+++ b/docs/superpowers/plans/2026-06-04-config-schema-reorg.md
--- a/docs/superpowers/plans/2026-06-04-rust-native-ocr-plan.md
+++ b/docs/superpowers/plans/2026-06-04-rust-native-ocr-plan.md
@@ -0,0 +1,89 @@
+# Plan: Rust 네이티브 OCR 엔진 (PP-OCRv5 ONNX) 구현
+
+spec: `docs/superpowers/specs/2026-06-04-rust-native-ocr-spec.md`. 브랜치 `feat/rust-native-ocr`.
+빌드 `CARGO_TARGET_DIR=/build/out/cargo-target`, 테스트 **`-j 8`**(절대 `-j 1` 금지), touched 크레이트 위주(`-p kebab-parse-image -p kebab-app -p kebab-config`).
+참조 구현: `oar-ocr`(Apache-2.0) 소스 + Python PaddleOCR + 검증된 PoC `/build/cache/ocr-bench/{rust-poc,onnx,rc9-spike}/`(변환 ONNX + rc.9 동작 확인).
+
+## Task 0a — 레퍼런스 골든 하네스 (C1 — 최우선 선행, executor 차단 제거)
+**T3/T5 골든은 oar-ocr 로 못 만든다**(중간 텐서 미노출, PoC 는 최종텍스트만). 먼저 Python `onnxruntime` 직접(oar-ocr X)으로 변환 모델을 돌려 fixture 별 중간 산출을 골든으로 덤프:
+- 입력: `/build/dogfood/corpus/images/synthetic-ocr-bench/` fixtures + 변환 ONNX(`/build/cache/ocr-bench/onnx/`).
+- 덤프(JSON/npy, repo `crates/kebab-parse-image/tests/golden/`): (a) det 확률맵 슬라이스, (b) threshold 후 박스 폴리곤, (c) **rec 원시 logits `[T,C]`**, (d) 디코드 문자열, (e) 전처리 텐서 일부값.
+- **M2 해결**: 알려진 텍스트라인 crop 의 logits + argmax 로 **blank 인덱스 + dict 11,945→클래스 11,947 매핑(+2 정체)을 경험적으로 도출**해 plan/주석에 사실로 기록(추정 금지). 경계문자(dict 첫/끝) 포함 골든.
+- 도구: 기존 venv `/build/cache/ocr-bench/venv`(onnxruntime 직접 설치) 또는 paddleocr API 의 raw 단계. 하네스 스크립트는 `/build/cache/ocr-bench/` 에 보관(런타임 의존 아님, 골든 생성 전용).
+- 수용: 각 fixture 골든 파일 생성 + blank 인덱스 문서화. 이후 T3~T5 가 이 골든에 핀.
+
+## Task 0 — 모델 번들 (결정 C-1: include_bytes, release feature 게이트)
+- 변환 ONNX(이미 존재: `/build/cache/ocr-bench/onnx/{ppocrv5_mobile_det.onnx, korean_ppocrv5_mobile_rec.onnx, korean_dict.txt}`)를 repo `crates/kebab-parse-image/assets/paddleocr-onnx/` 에 배치(+NOTICE, Apache-2.0).
+- `bundled-ocr-models` cargo feature: on 이면 `include_bytes!` 로 임베드, off(dev 기본)면 config override 경로 필수. release 빌드는 feature on.
+- 대안 C-2/C-3 는 빌드/링크 부담 측정 후 폴백(spec §모델 배포). 17MB 임베드의 dev 링크 영향 먼저 측정 — 과하면 C-2(repo 벤더 + OUT_DIR) 전환.
+- **assets 17MB 커밋 방식 결정(M4/packaging)**: git-LFS 권장(clone/`cargo package` 비대 회피). `.gitattributes` 에 `*.onnx filter=lfs`. NOTICE(Apache-2.0) 동반.
+- **테스트 모델 출처(M4)**: OCR 단위/e2e 테스트는 `bundled-ocr-models` feature 무관하게 `KEBAB_TEST_OCR_MODEL_DIR`(기본 `assets/paddleocr-onnx/`)에서 로드. 모델 없으면 `#[ignore]` 가 아니라 명확 skip+경고(CI 는 assets 존재 가정). dev 빌드 OCR 테스트가 모델 못 찾아 실패하는 모호함 제거.
+- 수용: feature on 빌드 임베드 확인, off 빌드 정상, 테스트가 assets 에서 모델 로드.
+
+## Task 1 — 의존성 (kebab-parse-image/Cargo.toml)
+- `ort = { workspace = true, features = ["ndarray", "download-binaries"] }`(C1: 단독빌드 링크, nli 선례 주석). `ndarray = { workspace = true }`. `imageproc`(연결요소/윤곽).
+- `ort-sys` caret 으로 rc.12 끌려가지 않게 Cargo.lock 정합 확인(rc.9 고정). unclip 다각형 offset 은 **pure-Rust 직접 구현**(clipper2 C++ FFI 회피 — spec).
+- 수용: `cargo build -p kebab-parse-image -j 8` 링크 성공(onnxruntime), `cargo tree` 에 ort 단일 rc.9.
+
+## Task 2 — OnnxPaddleOcr 골격 + 전처리 (kebab-parse-image)
+- **선행 사실 확인**: rc.9 `ort::Session` 이 `Send+Sync` 인지 먼저 확인(아니면 Mutex 래핑). 결과를 주석에 기록.
+- 신규 모듈 `paddle_onnx.rs`. `OcrEngine` 구현. **`engine_version`=생성 시 모델+dict blake3 1회 계산해 String 캐시**(m3: per-asset 재해시 금지 — `ingest_config_signature` 가 자산마다 호출). format 고정(후일 변경 시 mass 재색인 주의).
+- det/rec `ort::Session` 2개 1회 로드 후 보관. **max_pixels 자체 bounds 적용**(spec 의 ocr.rs MIN/MAX clamp 은 Ollama private — paddle 은 자기 clamp 명시).
+- 전처리: 디코드(image)→긴변 max_pixels 축소→BGR mean/std 정규화→`Array4<f32>`.
+- 수용: 단위테스트 — 알려진 이미지→입력텐서 일부 값 골든(T0a).
+
+## Task 3 — det 후처리 (단계 단위, 골든벡터)
+- det Session 추론(`[1,1,H,W]` 확률맵, rc.9 `try_extract_tensor`→`ArrayViewD`) → threshold 0.3 이진화 → imageproc 연결요소/윤곽 → **min-area rotated-rect(rotating calipers 직접 구현)** → **unclip(pure-Rust 다각형 offset, ratio 1.5)** → 박스 Vec.
+- 수용: 합성 fixture 기대 박스 개수/대략 좌표 골든. min-area rect·unclip 각각 단위테스트.
+
+## Task 4 — crop + rectify
+- 회전 박스 → perspective/affine warp 로 수평 정렬(oar-ocr 가 제공하던 부분 이식).
+- 수용: 회전 텍스트 fixture → 정렬 crop 골든.
+
+## Task 5 — rec + CTC decode
+- crop→48×W 정규화→rec Session(`[1,T,C]`) → CTC greedy(argmax/timestep→연속중복 제거→blank 제거).
+- **blank 인덱스 + 11,945→11,947 매핑은 T0a 하네스에서 도출한 사실을 사용**(추정 금지). bounds-check(dict 길이≠클래스 시 생성 에러).
+- 수용: T0a 골든 logit→문자열 일치(blank/중복/**경계문자 dict 첫·끝** 포함).
+
+## Task 6 — 조립 + OcrText
+- 박스 reading-order(상→하,좌→우) → `OcrText{joined, regions:[OcrRegion{bbox,text,confidence}], engine, engine_version}`. per-region 실제 confidence(Ollama 상수1.0 대비 값 변화 — release note).
+- 수용: e2e — 합성 한/영 fixture **CER ≤ 0.05**, bbox>0. PoC 0.976 baseline 대비 회귀 없음.
+- **CER 게이트 실패 시 폴백 사다리(M3)**: ① T0a 단계 골든과 diff 해 어느 단계 divergence 인지 국소화 → ② det postproc(unclip/min-area rect)가 원인이면 **oar-ocr 의 해당 함수를 verbatim 이식**(Apache-2.0, NOTICE+파일별 출처 표기 — 코드 파생물) → ③ time-box(예 반나절) 초과 시 리더 escalate. 손수 재유도에 매몰 금지.
+
+## Task 7 — config (kebab-config)
+- `OcrCfg`: `engine` 값에 "paddle-onnx" 문서화(기본 "ollama-vision" 유지). 신규 override `det_model`/`rec_model`/`dict`(Option), `score_thresh`(0.3)/`unclip_ratio`(1.5)/`max_boxes`(1000). `KEBAB_IMAGE_OCR_*` env. serde default(forward-compat) + init 템플릿 노출.
+- 수용: override 미지정→번들 모델, 지정→그 경로 사용 테스트. config migrate(#198) 무수정 로드 회귀.
+
+## Task 8 — 엔진 팩토리 (kebab-app/lib.rs) — **4개 site 전부(M1)**
+구체타입 `OllamaVisionOcr` 가 박힌 곳이 4군데 — 누락 시 타입에러로 막힘:
+- `:360` image 엔진 생성 → `Box<dyn OcrEngine>` 팩토리(`match engine`: ollama-vision|paddle-onnx|err).
+- `:379` pdf 엔진 생성 → 동일 팩토리.
+- `:839` `ImagePipeline.ocr_engine` 필드 → `Option<&dyn OcrEngine>`.
+- `:1113`, `:2096` `pdf_ocr_engine: Option<&OllamaVisionOcr>` 함수 시그니처 2곳 → `Option<&dyn OcrEngine>`.
+- `apply_ocr_to_pdf_pages`(`pdf_ocr_apply.rs:93`)는 이미 `&dyn OcrEngine` — 스레딩만 변경, 헬퍼 불변. `--config` facade 스레딩(`OnnxPaddleOcr::new(cfg,…)`).
+- 수용: 팩토리 단위테스트(선택/미지값 에러). **ollama-vision 경로 출력 동일** 회귀 테스트(구체→dyn 전환 무영향).
+
+## Task 9 — 서명 cascade (C3, kebab-app)
+- `ingest_config_signature` image/pdf 브랜치 `|ocr:1:{model}` → `|ocr:1:{engine}:{engine_version}`(engine + 모델/dict blake3). 
+- 수용: (a)ollama↔paddle 동일model→서명다름 (b)engine_version 다름→다름 (c)search 등 무관→불변. → 엔진/모델 변경 시 v0.26.2 자동 재색인.
+
+## Task 10 — 에러 매트릭스 (spec §에러 처리)
+- 다운로드/blake3 실패→fail-fast, 디코드불가→skip+provenance, det 0박스→`OcrText{"",[]}` 성공, rec 빈→박스skip, 박스폭증→max_boxes 절단+로그, dict 불일치→생성에러.
+- 수용: 각 케이스 단위/통합 테스트.
+
+## Task 11 — 검증 게이트
+- `cargo clippy --workspace --all-targets -j 8 -- -D warnings` 0.
+- `cargo test -p kebab-parse-image -p kebab-app -p kebab-config -j 8` 통과(+ `-p kebab-parse-image` 단독 링크 확인).
+- 스모크: `engine="paddle-onnx"` 이미지 ingest→FTS5 hit, 큰 페이지 CPU <5초.
+
+## Task 12 — 문서 + 버전 + 도그푸딩
+- README(Configuration: `image.ocr.engine`+모델 번들), docs/SMOKE(config 예시), HANDOFF 1줄, docs/ARCHITECTURE(OCR 백엔드/그래프), HOTFIXES dated entry.
+- Cargo.toml workspace version **minor bump**(+Cargo.lock). release notes(엔진 추가/per-region confidence/오프라인).
+- 도그푸딩: 사용자 실제 이미지·책 스캔 정확도·속도 → HOTFIXES + release notes evidence.
+- 결과 요약 `/tmp/rust-ocr-result.md`(게이트 + 스모크 + 도그푸딩 캡처).
+
+## 리뷰 루프
+완료 → 리더 clippy/타깃테스트(-j8) 독립 재확인 + paddle-onnx 스모크 → `gitea-pr`(title `feat(ocr): PP-OCRv5 ONNX Rust 네이티브 OCR 엔진`) → 리뷰 루프 → 사용자 머지. 모델 ONNX 는 release feature/asset 로 동반.
+
+## 단계 의존
+**T0a(레퍼런스 골든+blank 도출) 최우선 선행** → T0(번들),T1(deps) → T2→T3→T4→T5→T6(파이프라인 순차, 각 T0a 골든에 핀) ∥ T7(config) → T8(팩토리 4site)→T9(서명)→T10(에러) → T11 게이트 → T12 문서. T3~T5 가 핵심 난도(직접 이식), T0a 골든+T6 폴백사다리로 회귀·매몰 차단. T8 의 정확한 라인(:1113/:2096 등)은 구현 시점 grep 으로 재확인(코드 이동 가능).
--- a/docs/superpowers/specs/2026-06-03-ocr-toggle-invalidation-spec.md
+++ b/docs/superpowers/specs/2026-06-03-ocr-toggle-invalidation-spec.md
@@ -0,0 +1,55 @@
+# Spec: ingest 출력에 영향 주는 모든 설정 변경 시 자동 재색인 (skip 무효화 일반화)
+
+**날짜**: 2026-06-03
+**유형**: bug fix (patch)
+**근거**: `[image.ocr]`/`[image.caption]` 를 off→색인→on 으로 바꿔도 증분 skip 이 이미지를 "Unchanged" 로 건너뛴다. 더 일반적으로, `try_skip_unchanged` 가 자산 내용(blake3)+`parser_version`+`chunker_version`+`embedding_version` 만 비교하는데, **ingest 산출물을 바꾸는 다른 설정들**(청킹 파라미터, OCR/caption, pdf.ocr, 코드 ingest 옵션)이 이 셋 중 어디에도 반영되지 않아 변경해도 재색인이 안 된다. 사용자 요구: **OCR/caption 뿐 아니라 ingest 출력에 영향 주는 모든 설정**이 같은 방식으로 동작(변경→영향 자산 자동 재색인). 결과 포맷·인터페이스·새 플래그 변화 없음(내부 skip 판정 정정) → **patch**.
+
+## 동작 사실 (코드 근거)
+- `try_skip_unchanged`(lib.rs:866)는 `get_document_by_workspace_path` 로 기존 doc 조회 후 `existing_doc.parser_version != current_parser_version`(line 959) 면 재색인(cascade). **조회는 workspace_path** 이므로 doc_id 파생과 무관 — 비교는 저장된 `parser_version` 필드 대 현재값.
+- 각 경로가 상수 parser_version 을 넘김: md `md-heading-v1`(351), image `image-meta-v1`(1532), pdf `pdf-text-v1`(2109), code 등. 청킹 파라미터(`target_tokens`/`overlap_tokens`/`respect_markdown_headings`)는 `chunker_version` 상수에 안 들어가 변경해도 재청킹 안 됨(동일 갭).
+
+## 설계: per-asset-type "ingest config signature" 를 effective parser_version 에 폴딩
+
+`try_skip_unchanged` 에 넘기는 `current_parser_version` 과 **persist 되는 doc 의 `parser_version` 필드**를, 그 자산 타입의 **ingest 산출물에 영향을 주는 설정 전체의 결정적 서명**을 포함한 composite 로 만든다. 두 값이 같은 함수에서 나오므로, 관련 설정이 바뀌면 다음 run 비교가 mismatch → **영향 받는 자산만** 자동 재색인. doc_id 는 path 조회라 기존대로(안정, orphan churn 회피).
+
+### 어떤 설정이 어느 자산에 영향 (서명 구성)
+공통 헬퍼 `ingest_config_signature(config, media_type) -> String`. **ingest 산출물에 영향 주는 것만** 포함(아래 외 search/rag/nli/ui/logging/storage/workspace 는 **제외** — 바뀌어도 재색인 안 함):
+
+- **공통(모든 타입)**: `[chunking]` target_tokens, overlap_tokens, respect_markdown_headings, chunker_version. (embedding model/dim 은 이미 `embedding_version` cascade 가 담당 — 서명에 중복 포함 불필요, 단 일관성 위해 포함해도 무방.)
+- **image**: + `[image.ocr]` enabled (+enabled 면 model), `[image.caption]` enabled (+enabled 면 prompt_template_version).
+- **pdf**: + `[pdf.ocr]` enabled (+enabled 면 model, always_on).
+- **code**: + `[ingest.code]` skip_generated_header, max_file_bytes, max_file_lines, extra_skip_globs, ast_chunk_max_lines, fallback_lines_per_chunk, fallback_lines_overlap.
+- **markdown**: 공통만.
+
+서명 형식: 결정적 문자열 또는 그 blake3-12. 예 `image-meta-v1|chunk:500:80:true|ocr:1:qwen2.5vl:3b|cap:1:caption-v1`. off/미적용 항목은 안정적 표현(빈값)으로 — 동일 설정 재실행은 서명 동일 → **불필요 재색인 0**.
+
+## 작업 (kebab-app)
+1. `ingest_config_signature(config, media_type)` 헬퍼 추가(위 매핑). 출력 결정적(필드 순서 고정, Vec 는 join).
+2. 각 ingest 경로에서 effective parser_version = `format!("{base}|{signature}")` 또는 base 를 서명으로 감싼 값으로:
+   - md(351), image(1532), pdf(2109), code 경로의 `*_parser_version` 계산을 composite 로.
+   - **persist 전 `canonical.parser_version` 을 동일 composite 로 override**(extractor 가 박은 상수 대신). skip-check 와 저장값이 같아야 함.
+3. doc_id: 변경 불필요(workspace_path 조회). composite 는 비교 필드에만.
+
+## 동작 / 호환
+- ingest 영향 설정(청킹/OCR/caption/pdf.ocr/code) 변경 또는 모델·prompt 변경 → effective parser_version 변화 → **영향 자산만** `--force-reingest` 없이 자동 재색인(+UPSERT/purge). 비영향 설정(search/rag/ui/log) 변경 → 재색인 0.
+- **업그레이드 1회 효과**: 기존 doc 의 저장 parser_version(상수)이 새 composite 와 달라 → 업그레이드 후 첫 ingest 에서 전 자산 1회 재색인(현재 설정대로). 마크다운/코드도 1회 재청킹되나 embedding 은 V012 캐시 히트라 재임베딩 비용 작음. (HOTFIXES/release notes 에 1회 재색인 명시.)
+- `--force-reingest` 는 전체 강제용으로 그대로 유지.
+
+## 검증 기준
+- clippy 0. `cargo test -p kebab-app -p kebab-parse-image -p kebab-parse-pdf -p kebab-parse-code -p kebab-chunk -j 8` 통과 (**전체 워크스페이스 `-j 1` 금지 — `-j 8`**).
+- 신규 테스트(자산 타입별):
+  - image.ocr off→on / caption off→on → 해당 이미지 재색인(skip 아님). off→off, on→on(동일) → skip 유지.
+  - pdf.ocr off→on → PDF 재색인. 동일 설정 → skip.
+  - chunking target_tokens 변경 → md/code/image/pdf 전부 재색인. 변경 없으면 skip.
+  - ingest.code 옵션 변경 → 코드 자산 재색인, 이미지/md 는 영향 받되 **공통(chunking) 변경 아니면 코드만** (code 전용 설정은 code 서명에만).
+  - search/rag/ui 설정 변경 → 재색인 0 (회귀 가드, 중요).
+  - 동일 config 재실행 → 전 자산 skip(불필요 재색인 0) — 회귀 가드.
+- 스모크: 이미지 ocr off 색인 → config ocr on → `kebab ingest`(force 없이) → 그 이미지만 재색인 확인.
+
+## 비범위
+- 새 config 키/CLI 플래그/wire(없음).
+- 서명에 max_pixels/languages/timeout 같은 *런타임 비-산출* 파라미터는 **제외**(산출물 불변 → 과도 무효화 회피). 포함 기준 = "그 값이 바뀌면 색인되는 chunk/embedding 내용이 달라지는가".
+- search/rag/nli/ui/logging/storage/workspace 설정(ingest 산출 무관) 제외.
+
+## 문서/버전
+- tasks/HOTFIXES dated entry(일반화 + 1회 재색인 안내). Cargo.toml **patch bump (0.26.1 → 0.26.2)**(+Cargo.lock). README/wire 변화 없음. HANDOFF 1줄(선택).
--- a/docs/superpowers/specs/2026-06-04-config-schema-reorg-design.md
+++ b/docs/superpowers/specs/2026-06-04-config-schema-reorg-design.md
@@ -0,0 +1,297 @@
+# config 스키마 재편 (v2 → v3): 미디어별 `[ingest]` 통합 + per-option 주석
+
+- 상태: 설계 확정 (brainstorming 완료)
+- 작성일: 2026-06-04
+- 선행: `docs/superpowers/specs/2026-05-31-config-migration-design.md` (마이그레이션 엔진), `#197`(엔진), `#198`(`kebab config migrate` surface)
+- 영향 crate: `kebab-config`(스키마+마이그레이션), `kebab-app`(call-site sweep + signature), `kebab-eval`(config_snapshot), `kebab-cli`(`config migrate`/`init` 출력)
+- contract_sections: design §6 (Config schema / XDG), §9 (versioning cascade — signature 불변 보장)
+
+## 1. 동기
+
+옵션이 누적되며 `config.toml`(13 섹션 / ~60 필드)이 다음 군더더기를 갖게 됨:
+
+1. **OCR 중복·비대칭** — `[image.ocr]` 와 `[pdf.ocr]` 가 `enabled/engine/model/endpoint/languages/max_pixels/request_timeout_secs` 를 거의 그대로 중복. 게다가 paddle-onnx 모델 경로(`det_model`/`rec_model`/`dict`/`score_thresh`/`unclip_ratio`/`max_boxes`)는 `[image.ocr]` 에만 존재하고 PDF paddle 경로가 거기를 참조(`kebab-app/src/lib.rs:3102` `ocr_engine_version_for_sig` 가 `config.image.ocr` 를 읽음) — "pdf 설정인데 image 밑을 봐야 하는" 숨은 비대칭.
+2. **미디어별 설정 산재** — 이미지 `[image]`, PDF `[pdf]`, 코드 `[ingest.code]`, 청킹 `[chunking]`. "형식 X 설정이 어디 있나"의 규칙이 없음.
+3. **`endpoint` 4중복** — `models.llm`/`models.embedding`/`image.ocr`/`pdf.ocr`. "비우면 `models.llm.endpoint` fallback" 규칙이 코드에만 있고 파일엔 안 보임. (단, **컴포넌트별 endpoint 는 실사용 중** — embedding 로컬 + llm 원격 — 이므로 통합 금지.)
+4. **`request_timeout_secs` 3중복** + 각각 "`0` 은 비활성화 아님" 함정.
+5. **`kebab init` 이 60+ 필드 일괄 방출** — 실제 사용자가 만지는 건 `workspace.root`/endpoint/모델명 정도.
+6. 사용자 실파일에서 추가 관찰: `score_gate = 0.30000001192092896`(f32→f64 직렬화 찌꺼기), `engine="paddle-onnx"` 인데 `model="gemma4:e4b"` 가 남는 죽은 필드.
+
+## 2. 목표 / 비목표
+
+**목표**
+
+- 미디어 형식 설정을 `[ingest.*]` 한 우산 아래로 일관 배치 (향후 새 형식 = `[ingest.<형식>]` 한 곳 추가).
+- OCR 비대칭 제거: image·pdf 가 **각자 OCR 전체(paddle 경로 포함)를 독립 보유**(완전 대칭).
+- **무손실 변환**: 기존 v2 파일의 모든 값·주석·순서·사용자 대안 주석 줄을 보존.
+- **per-option 주석**: 각 키 옆 한 줄 설명을 `kebab init` 출력과 신규 추가 키에 부착.
+- 업그레이드 시 **불필요한 재색인 0** (parser_version signature 불변).
+- env override 이름 **무파손**.
+
+**비목표 (YAGNI)**
+
+- config 값 의미 검증(범위 체크 등) — 별개.
+- 다운그레이드(v3→v2).
+- 노브 숨기기/축소 — 명시적으로 제외(사용자가 "온전한 변환" 선택). 전 옵션을 잘 문서화한 완전체 유지.
+- endpoint 통합 — 컴포넌트별 override 유지(실사용).
+- **load 시 파일 자동 쓰기** — 여전히 비목표(2026-05-31 spec 계승). 단 §5.3 의 *메모리 내* 변환은 쓰기가 아니므로 별개로 허용.
+
+## 3. 새 스키마 (v3)
+
+per-option 주석을 부착한 `kebab init` 출력 형태(값은 기본값):
+
+```toml
+# kebab config — `~/.config/kebab/config.toml`.
+# (헤더: workspace.root 경로 규칙 / 지원 형식 / KEBAB_* override — 기존 헤더 계승)
+schema_version = 3
+
+# 색인 대상 워크스페이스.
+[workspace]
+root = "~/KnowledgeBase"      # 색인 루트. 절대/~/${VAR}/상대(=이 파일 기준).
+exclude = [".git/**", "node_modules/**", ".obsidian/**"]  # denylist glob.
+
+# XDG 저장 경로(데이터/sqlite/벡터/에셋/모델).
+[storage]
+data_dir = "${XDG_DATA_HOME:-~/.local/share}/kebab"  # 모든 산출물 루트.
+sqlite = "{data_dir}/kebab.sqlite"   # 메타·FTS5 DB.
+vector_dir = "{data_dir}/lancedb"    # 임베딩 벡터 스토어.
+asset_dir = "{data_dir}/assets"      # 원본 사본(_external 등).
+artifact_dir = "{data_dir}/artifacts"
+model_dir = "{data_dir}/models"      # fastembed/candle/nli 모델 캐시.
+runs_dir = "{data_dir}/runs"         # eval run 산출.
+copy_threshold_mb = 100              # 이 크기 초과 파일은 사본 대신 참조.
+
+# 다국어 sentence embedding. dim 불일치 시 검색 0건.
+[models.embedding]
+provider = "fastembed"   # fastembed | candle | ollama | none.
+model = "multilingual-e5-large"
+version = "v1"           # 모델 정체성 일부(캐시 키). 모델 바꾸면 함께 갱신.
+dimensions = 1024        # 모델 출력 차원. 틀리면 검색 0건.
+batch_size = 64
+num_threads = 0          # candle 전용 CPU 스레드 cap(0=auto). NUMA 회피 레버.
+# endpoint = "..."       # ollama provider 시 HTTP. 비우면 models.llm.endpoint fallback.
+
+# Ollama host:port + 모델.
+[models.llm]
+provider = "ollama"
+model = "gemma4:e4b"
+context_tokens = 32768
+endpoint = "http://127.0.0.1:11434"
+temperature = 0.0
+seed = 0
+request_timeout_secs = 300   # 단일 HTTP 상한. 0=즉시실패(비활성화 아님). 대형모델 CPU면 ↑.
+
+# NLI(groundedness) 모델.
+[models.nli]
+model = "Xenova/mDeBERTa-v3-base-xnli-multilingual-nli-2mil7"
+provider = "onnx"
+
+# 색인 공통(병렬도 + 파일시스템 watch).   ← 기존 [indexing]
+[ingest]
+max_parallel_extractors = 2
+max_parallel_embeddings = 1
+watch_filesystem = false
+
+# 청크 크기·오버랩·heading 존중 (markdown/pdf/code/image 모든 형식 공통).  ← 기존 [chunking]
+[ingest.chunking]
+target_tokens = 500
+overlap_tokens = 80
+respect_markdown_headings = true
+chunker_version = "md-heading-v1"
+
+# code ingest skip 정책(.gitignore 자동 honor).
+[ingest.code]
+skip_generated_header = true
+max_file_bytes = 262144
+max_file_lines = 5000
+extra_skip_globs = []
+ast_chunk_max_lines = 200
+fallback_lines_per_chunk = 80
+fallback_lines_overlap = 20
+
+# 이미지 OCR(기본 off, asset 당 비용).   ← 기존 [image.ocr]
+[ingest.image.ocr]
+enabled = false
+engine = "ollama-vision"     # ollama-vision | paddle-onnx.
+model = "gemma4:e4b"         # ollama-vision 전용. paddle-onnx 는 번들 모델 사용(이 값 무시).
+languages = ["eng", "kor"]
+max_pixels = 1600
+request_timeout_secs = 300   # 0=즉시실패(비활성화 아님).
+# --- paddle-onnx 전용(engine=paddle-onnx 일 때만) ---
+# det_model = "..."          # 비우면 번들 ppocrv5_mobile_det.onnx.
+# rec_model = "..."          # 비우면 번들 korean rec.
+# dict = "..."               # 비우면 번들 korean_dict.txt.
+score_thresh = 0.3           # DBNet box 점수 하한.
+unclip_ratio = 1.5           # box 패딩 비율.
+max_boxes = 1000             # 이미지당 box cap(runaway guard).
+
+# 이미지 캡션(기본 off).   ← 기존 [image.caption]
+[ingest.image.caption]
+enabled = false
+max_pixels = 768
+prompt_template_version = "caption-v1"
+
+# scanned PDF page-단위 OCR(기본 off, page 당 비용).   ← 기존 [pdf.ocr]
+[ingest.pdf.ocr]
+enabled = false
+always_on = false            # true=모든 page vision 호출(vector PDF dual-text).
+engine = "ollama-vision"     # ollama-vision | paddle-onnx.
+model = "qwen2.5vl:3b"       # ollama-vision 전용. paddle-onnx 는 번들 모델 사용.
+languages = ["eng", "kor"]
+max_pixels = 2048
+request_timeout_secs = 180   # 0=즉시실패(비활성화 아님).
+valid_ratio_threshold = 0.5  # 유효문자 비율 < 이면 scanned 로 판정→OCR fallback.
+min_char_count = 20          # page 문자수 < 이면 auto-scanned.
+lang_hint = "kor"            # 단일 page lang hint(비우면 없음).
+# --- paddle-onnx 전용(대칭 신규) ---
+# det_model / rec_model / dict = "..."   # 비우면 번들.
+score_thresh = 0.3
+unclip_ratio = 1.5
+max_boxes = 1000
+
+# 검색 기본 k·stale 기준·fusion.
+[search]
+default_k = 10
+hybrid_fusion = "rrf"
+rrf_k = 60
+snippet_chars = 220
+cache_capacity = 256
+stale_threshold_days = 30
+
+# 답변 생성: prompt 템플릿·score gate·multi-hop·NLI.
+[rag]
+prompt_template_version = "rag-v3"
+score_gate = 0.3             # serialize_with 헬퍼로 직렬화 깔끔(기존 f32 찌꺼기 제거).
+explain_default = false
+max_context_tokens = 8000
+multi_hop_max_depth = 3
+multi_hop_max_sub_queries_per_iter = 5
+multi_hop_max_pool_chunks = 15
+nli_threshold = 0.0          # 0=NLI 게이트 off.
+
+# TUI 팔레트.
+[ui]
+theme = "dark"
+
+# ingest 로그(기본 on).
+[logging]
+ingest_log_enabled = true
+ingest_log_dir = "{state_dir}/logs"
+keep_recent_runs = 100
+retention_days = 30
+```
+
+## 4. 필드 매핑 (v2 → v3)
+
+| v2 위치 | v3 위치 | 비고 |
+|---------|---------|------|
+| `[workspace]` `[storage]` `[search]` `[rag]` `[ui]` `[logging]` `[models.*]` | 동일 | 변경 없음 |
+| `[indexing].*` (3키) | `[ingest].*` (bare 키) | `IndexingCfg` 해체 → `IngestCfg` 스칼라 |
+| `[chunking]` | `[ingest.chunking]` | 이름 의도적으로 `markdown` 아님(전 형식 공통) |
+| `[ingest.code]` | `[ingest.code]` | 이미 nested — 무이동 |
+| `[image.ocr]` | `[ingest.image.ocr]` | 키 동일 |
+| `[image.caption]` | `[ingest.image.caption]` | 키 동일 |
+| `[pdf.ocr]` | `[ingest.pdf.ocr]` | 키 동일 + **paddle 6키 대칭 신규** (`det_model`/`rec_model`/`dict`/`score_thresh`/`unclip_ratio`/`max_boxes`) |
+
+신규 키(pdf paddle 대칭)는 모두 `#[serde(default)]` + `Option`/기본값 → v2 파일에 없어도 무해.
+
+## 5. Rust 구조 변경 (`kebab-config/src/lib.rs`)
+
+### 5.1 구조체
+
+```rust
+pub struct Config {
+    pub schema_version: u32,
+    pub workspace: WorkspaceCfg,
+    pub storage: StorageCfg,
+    pub models: ModelsCfg,
+    pub ingest: IngestCfg,   // ← indexing/chunking/image/pdf 흡수
+    pub search: SearchCfg,
+    pub rag: RagCfg,
+    pub ui: UiCfg,
+    pub logging: LoggingCfg,
+    #[serde(skip)] source_dir: Option<PathBuf>,
+}
+
+pub struct IngestCfg {
+    // ← 기존 IndexingCfg (스칼라 먼저: toml 직렬화는 스칼라가 테이블보다 앞)
+    pub max_parallel_extractors: u32,
+    pub max_parallel_embeddings: u32,
+    pub watch_filesystem: bool,
+    // 하위 테이블
+    pub chunking: ChunkingCfg,
+    pub code: IngestCodeCfg,
+    pub image: ImageCfg,     // { ocr: OcrCfg, caption: CaptionCfg }
+    pub pdf: PdfCfg,         // { ocr: PdfOcrCfg }
+}
+```
+
+- `IndexingCfg` 구조체 삭제(스칼라로 흡수). `ChunkingCfg`/`ImageCfg`/`OcrCfg`/`CaptionCfg`/`PdfCfg`/`IngestCodeCfg` **내부 필드 불변**(부모 경로만 이동).
+- `PdfOcrCfg` 에 paddle 6키 대칭 추가.
+- 제거된 top-level 필드: `indexing`/`chunking`/`image`/`pdf`.
+- 스칼라-우선 필드 순서로 `defaults_are_serde_roundtrip_stable` 유지.
+
+### 5.2 call-site sweep (~65곳, 7 src 파일)
+
+기계적 치환: `config.chunking.X`→`config.ingest.chunking.X`, `config.image.ocr`→`config.ingest.image.ocr`, `config.pdf.ocr`→`config.ingest.pdf.ocr`, `config.indexing.X`→`config.ingest.X`. 대상: `kebab-app/src/{lib.rs,app.rs,schema.rs}`, `kebab-eval/src/runner.rs`. `kebab-parse-image` 는 leaf 구조체(`&OcrCfg` 등) 직접 수령 → 무영향(확인됨).
+
+### 5.3 load 시 메모리 내 자동 변환 (정합성 필수)
+
+v3 는 최초의 **non-additive rename** 이라, 미변환 v2 파일을 v3 struct 로 deserialize 하면 `[chunking]`/`[image]`/`[pdf]`/`[indexing]` 을 못 찾아 **사용자 설정이 조용히 기본값으로 유실**. (이전 마이그레이션은 전부 additive 라 serde default 로 load 호환됐음 — 이 가정이 v3 에서 처음 깨짐.)
+
+→ `Config::from_file` 변경: 텍스트의 `schema_version < CURRENT` (또는 legacy 테이블 탐지) 시 `migrate::migrate_document(text)` 를 **메모리에서** 적용한 `new_text` 를 deserialize. **디스크 쓰기 없음**(파일 갱신은 여전히 `kebab config migrate` 전용 — 2026-05-31 spec 의 "자동 쓰기 비목표" 계승; 메모리 변환은 쓰기가 아니므로 무충돌). 1회성 `tracing::warn!`: "config 가 schema vN 입니다 — 이번 실행은 메모리에서 v3 로 변환됨. 파일 갱신은 `kebab config migrate`."
+
+- parse 실패 시 `migrate_document` 는 입력 그대로 반환 → 기존 `ConfigInvalid` 경로 유지.
+- `source_dir` stamp 는 변환 후 동일하게 `path.parent()`.
+
+## 6. 마이그레이션 `step_2_to_3` (`kebab-config/src/migrate.rs`)
+
+`run_steps` 에 `if from < 3 { step_2_to_3(doc, changes) }` 추가. `step_2_to_3` 는 **테이블 relocation**(toml_edit, 값·키주석·순서 보존):
+
+1. `[indexing]` 의 3키 → `[ingest]` bare 키로 이동. 원 `[indexing]` 제거.
+2. `[chunking]` 테이블 → `[ingest.chunking]` 로 이동(통째). 원 제거.
+3. `[image.ocr]`→`[ingest.image.ocr]`, `[image.caption]`→`[ingest.image.caption]`. 원 `[image]` 제거.
+4. `[pdf.ocr]`→`[ingest.pdf.ocr]`. 원 `[pdf]` 제거.
+5. **pdf paddle 동작 보존(중요)** — v2 는 pdf 가 paddle 일 때 `image.ocr` 의 paddle 값(`det_model`/`rec_model`/`dict`/`score_thresh`/`unclip_ratio`/`max_boxes`)을 빌려 썼다(§1 비대칭). 따라서 이동 직후 **`[image.ocr]` 의 이 6키 실제 값을 `[ingest.pdf.ocr]` 의 대칭 키로 복사**한다(사용자가 image paddle 을 튜닝한 경우까지 동작 동일 보장). 사용자가 둘 다 기본이면 복사값=기본값이라 무차. 복사는 사용자가 `[pdf.ocr]` 에 해당 키를 이미 명시한 경우엔 덮어쓰지 않음.
+6. 기존 `[ingest.code]` 는 그대로(이미 올바른 위치). 단 `[ingest]` 가 새로 bare 키를 받으므로 직렬화 순서 정합 확인.
+
+이동은 **user item 의 decor(값 뒤 인라인 주석 + 사용자 대안 주석 줄)를 동반**해야 함 — toml_edit 에서 `Table::remove` 로 떼어낸 `Item` 을 새 부모에 `insert`. 멱등(이미 v3 형태면 no-op).
+
+이동 후 기존 `reconcile(annotated_default, doc)` 가:
+- 빠진 키(특히 pdf paddle 대칭 6키) 를 주석과 함께 추가.
+- `schema_version` stamp → 3.
+
+`CURRENT_SCHEMA_VERSION: u32 = 3` 으로 bump.
+
+## 7. per-option 주석 인프라
+
+- `key_comment(path: &str) -> Option<&'static str>` 신설 (`section_comment` 자매). dotted leaf 경로(`ingest.chunking.target_tokens` 등) → 한 줄.
+- `annotate_table` 확장: 스칼라 leaf 에도 `key_comment` 가 있으면 인라인/prefix 주석 부착.
+- **부착 범위**: `annotated_default_document`(=`kebab init` + reconcile 참조원) 의 모든 키. reconcile 가 **새로 추가하는** 키만 주석 동반(기존 사용자 키는 값 불가침 → 주석 미주입, 사용자 대안 주석 보존).
+- §3 의 모든 키 주석 텍스트를 `key_comment` 에 등재(구현 시 일괄).
+
+## 8. 불변식 / 회귀 가드
+
+1. **signature 불변** — `ingest_config_signature`(lib.rs:3129) 출력 문자열이 v2 바이너리와 **바이트 동일**. 값 기반이라 struct 경로 변경과 무관해야 함. `ocr_engine_version_for_sig` 가 읽는 paddle 경로 소스를 image signature 는 `config.ingest.image.ocr` 로, **pdf signature 는 `config.ingest.pdf.ocr` 의 신규 대칭 키**로 갱신. 동작 보존은 §6.5 의 값 복사(image paddle 값 → pdf 대칭 키)로 성립 — 마이그레이션된 파일에서 pdf 대칭 키 = v2 시절 image 값이므로 signature 동일. 골든 문자열 회귀 테스트 필수.
+2. **env 이름 보존** — `apply_env` whitelist 의 LHS(키 문자열) 전부 그대로, RHS(대입 대상)만 새 struct 경로. 신규 pdf paddle 키만 `KEBAB_PDF_OCR_{DET_MODEL,REC_MODEL,DICT,SCORE_THRESH,UNCLIP_RATIO,MAX_BOXES}` 추가. 기존 env 테스트 전부 green 유지.
+3. **무손실 골든** — 사용자 실제 v2 config(첨부본; `score_gate` 찌꺼기·주석 대안 줄 포함)를 fixture 로: `migrate_document` → (a) 모든 사용자 값 보존, (b) 사용자 주석/대안 줄 보존, (c) `[ingest.image.ocr]` 등 신 위치 존재, (d) 결과가 v3 `Config` 로 parse 되고 값이 원 의미와 동일, (e) 재실행 멱등.
+4. **load 자동변환** — v2 텍스트를 `Config::from_file` 로 읽으면(디스크 미변경) `config.ingest.chunking.target_tokens` 등이 사용자 값으로 채워짐(기본값 유실 없음) 테스트.
+5. **float 직렬화 정리** — `Config::defaults()` 직렬화에 `0.30000001192092896` 부재, `score_gate = 0.3`. 구현: f32 필드에 `#[serde(serialize_with = "ser_f32_clean")]`(f32 Display 의 shortest round-trip 을 f64 로 재파싱해 직렬화) — struct 타입·호출부 무변경, kebab-config 국소. 사용자 기존 파일의 찌꺼기 값은 toml_edit 보존(값 불가침)이라 그대로 — 재생성 시에만 정리됨(비목표 §2 정합).
+
+## 9. 버전 / 문서 cascade
+
+- **minor bump** (인터페이스 변경: config 섹션 rename + 신규 키). `Cargo.toml` workspace version.
+- **schema_version 2→3** (위).
+- **도그푸딩 필수**(CLAUDE.md Dogfood trigger: CLI/config surface) — `kebab config migrate` 를 실제 v2 파일(첨부본)에 돌려 무손실 + 자동변환 + 재색인 0 확인. evidence → HOTFIXES + release notes.
+- **문서 동기화(같은 PR)**: README Configuration 섹션 + `docs/SMOKE.md` config 예시 블록(새 레이아웃) + HOTFIXES dated entry + `2026-05-31-config-migration-design.md` 의 Risks/notes 에 v3 rename 교차링크.
+
+## 10. 리스크
+
+| 리스크 | 완화 |
+|--------|------|
+| 테이블 이동 시 주석 유실 | toml_edit `remove`→`insert` 로 `Item` 통째 이동, 골든 테스트(§8.3) |
+| signature 변동→전체 재색인 | 골든 문자열 회귀 테스트(§8.1), 값 포맷 보존 |
+| pdf paddle 대칭 추가가 기존 pdf paddle 동작 변경 | §6.5 마이그레이션이 image paddle 6키 실제 값을 pdf 대칭 키로 복사 → 동작·signature 동일(§8.1) |
+| call-site 누락 | 컴파일러가 강제(필드 제거→ 미수정 site 컴파일 에러), clippy gate |
+| 메모리 자동변환 매 load 비용 | toml_edit parse 1회/실행, 무시 가능 |
+```
--- a/docs/superpowers/specs/2026-06-04-rust-native-ocr-spec.md
+++ b/docs/superpowers/specs/2026-06-04-rust-native-ocr-spec.md
@@ -0,0 +1,192 @@
+# Spec: Rust 네이티브 OCR 엔진 (PP-OCRv5 ONNX, in-process)
+
+**날짜**: 2026-06-04
+**유형**: feature (minor) — 신규 OCR 엔진 + config 키 + 동작 변화
+**상태**: draft (self-review 대기)
+**contract_sections**: design §6 (parse/extract), §8 (deps), §9 (versioning cascade)
+
+## 동기
+
+현재 이미지/PDF OCR 은 Ollama Vision LLM(`gemma4:e4b` 8B) 1콜(`crates/kebab-parse-image/src/ocr.rs`, `OllamaVisionOcr`). 사용자 실측 문제:
+
+- 실제 이미지 한 장당 **~50초**(VLM 은 글자를 토큰 단위로 생성 → 조밀 페이지는 본질적으로 느림). 모델을 바꿔도(qwen2.5vl:3b GPU 20~28초) 사용자 허용치 미달.
+- 사용자 결정: **배치 ingest 용도 + Python 의존 불가 + Rust 내장**.
+
+### 근거 벤치 (2026-06-04, `/build/dogfood/logs/2026-06-04-ocr-model-bench.md`)
+
+| 방식 | 작은 이미지 | 초대형 1757×2644 | 정확도 | 비고 |
+|---|---|---|---|---|
+| gemma4:e4b 8B VLM (GPU) | 11초 | 43초 | 0.65~0.82 | 현재 |
+| qwen2.5vl:3b VLM (GPU) | 3.6초 | 20초 | 0.93 | 속도 미달 |
+| **PP-OCRv5 mobile ONNX, Rust (CPU)** | **0.05초** | **2.75초** | **0.976** | **PoC 검증됨** |
+
+VLM 은 생성 병목으로 탈락. **검출+인식형 전용 엔진(PP-OCRv5)을 ONNX 로 Rust in-process 실행**이 속도·정확도·한국어·단일바이너리 모두 만족. PoC: `oar-ocr` 0.6.3 + `ort` 로 위 수치 확인(오류는 띄어쓰기뿐, 한국어 오인식 0). PoC 코드/모델: `/build/cache/ocr-bench/{rust-poc,onnx}/`.
+
+## 핵심 설계 결정: oar-ocr 미채택, 핀 ort 위 직접 구현
+
+PoC 는 `oar-ocr` 0.6.3 으로 검증했으나 **프로덕션 의존성으로는 쓰지 않는다**. 이유(load-bearing):
+
+- kebab 은 `ort = "=2.0.0-rc.9"` 를 **의도적 핀**(workspace `Cargo.toml:195-204`): fastembed 4.9 의 ONNX Runtime+tokenizer 스택을 워크스페이스 단일 버전으로 유지. `ndarray = "0.16"` 도 동일.
+- `oar-ocr` 0.6.3 은 `ort 2.0.0-rc.12` + `ndarray 0.17` 요구. `ort` 는 `ort-sys` 가 onnxruntime 네이티브 라이브러리를 `links` 하므로 **두 버전 공존 불가** → oar-ocr 채택 시 ort/ndarray 를 bump 해야 하고, 이는 fastembed/kebab-nli/kebab-embed-candle 의 임베딩·NLI 스택을 흔든다(사용자 우선순위인 검색 품질 직결, [[search-quality-dogfood]]).
+
+**→ PaddleOCR 의 전/후처리(검출 DBNet postproc + 인식 CTC decode)를 kebab 의 기존 핀 `ort`(rc.9) 위에 직접 구현.** oar-ocr(Apache-2.0) 소스 + Python PaddleOCR 을 레퍼런스로. 공유 ort 라 새 네이티브 의존성 0, 임베딩 스택 무영향.
+
+### C2 검증 완료 (rc.9 스파이크, 2026-06-04)
+
+PoC 는 oar-ocr 경유 ort **rc.12** 로 돌았으므로, 핀 **rc.9** 가 paddle2onnx 산출 모델을 실제 로드/추론하는지 별도 검증함(`/build/cache/ocr-bench/rc9-spike/`). 결과 **PASS**:
+- `ort = "=2.0.0-rc.9"` + `ort-sys = "=2.0.0-rc.9"`(caret 으로 rc.12 끌려가는 것 방지 — kebab Cargo.lock 과 동일) + `ndarray 0.16` + feature `["ndarray","download-binaries"]` 로 빌드/링크/onnxruntime 다운로드 성공.
+- det: 입력 `"x"` → 출력 `[1,1,640,640]`(DBNet 확률맵). rec: 출력 `[1,40,11947]`(timestep×클래스; dict 11,945 + blank/특수 = 11,947, CTC 정합 확인).
+- `try_extract_tensor::<f32>()` 는 rc.9 에서 `ArrayViewD<f32>` 반환(rc.12 의 `(shape,&[T])` 와 다름) — 구현 시 유의.
+- **함의**: 핀 ort 유지(ort/ndarray bump 불필요)로 임베딩 스택 무영향 확정. opset 호환 OK. 출력 형태가 후처리 설계(det threshold→박스 / rec CTC)와 일치.
+
+### 추가 의존성
+
+- `image`(이미 허용), `ndarray`(workspace `=0.16`), `ort`(workspace `=2.0.0-rc.9`, **features `["ndarray","download-binaries"]`**).
+  - **download-binaries 필수**: `kebab-parse-image` 는 fastembed 빌드그래프에 없어, 단독 빌드(`cargo test -p kebab-parse-image`)시 onnxruntime 링크 위해 명시 필요. `kebab-nli/Cargo.toml:23` 의 동일 선례 주석 그대로 따름.
+  - `ort-sys` 가 caret 으로 rc.12 로 끌려가지 않도록 workspace 핀과 Cargo.lock 정합 확인.
+- `imageproc` — det 확률맵 연결요소/윤곽 추출. **단 min-area rotated-rect 는 imageproc 미제공 → rotating-calipers 직접 구현**.
+- DBNet unclip(다각형 확장): **`clipper2` 는 C++ FFI 가능성 → single-binary/pure-Rust 위배 위험. 우선 pure-Rust 다각형 offset 직접 구현 또는 검증된 pure-Rust crate.** (plan 에서 clipper2 가 C++ 링크인지 확인 후 택일.)
+
+## 파이프라인 (OnnxPaddleOcr)
+
+`crates/kebab-parse-image/src/` 에 신규 모듈. `OcrEngine` trait(`ocr.rs:54`) 구현:
+
+```rust
+pub trait OcrEngine: Send + Sync {
+    fn engine_name(&self) -> &'static str;       // "paddle-onnx"
+    fn engine_version(&self) -> String;          // "ppocrv5-mobile-kor-v1" (+model hash)
+    fn recognize(&self, image_bytes: &[u8], lang_hint: Option<&Lang>) -> Result<OcrText>;
+}
+```
+
+`recognize` 단계 (PoC 와 동일 알고리즘):
+
+1. **디코드+다운스케일**: `image` 로 디코드 → 긴변 `max_pixels`(기본 1600) 로 축소(기존 `OcrCfg.max_pixels` 재사용, qwen 과 달리 PP-OCRv5 는 원본도 안전하나 속도 위해 유지).
+2. **검출(det)**: BGR 정규화 → det ONNX(`PP-OCRv5_mobile_det`) → 확률맵 → threshold(0.3) 이진화 → 윤곽(imageproc) → min-area rect → unclip(ratio 1.5) → 텍스트 박스 N개.
+3. **인식(rec)**: 각 박스 crop+회전보정 → 48×W 리사이즈/정규화 → rec ONNX(`korean_PP-OCRv5_mobile_rec`) → CTC greedy decode(dict 11,945자, blank 처리) → 텍스트+score.
+4. **조립**: 박스를 reading-order(상→하, 좌→우) 정렬 → `OcrText { joined, regions: Vec<OcrRegion{bbox,text,confidence}>, engine, engine_version }`. **Ollama 와 달리 per-line bbox/confidence 제공**(`OcrRegion` 풍부화).
+
+배치: PoC 는 박스별 순차 rec. 성능 충분(초대형 2.75초)하나, rec 를 ort 배치 입력으로 묶으면 추가 향상 가능(plan 에서 측정 후 결정).
+
+### 단계별 분해 (M1 — 각 단계 골든벡터 단위테스트)
+
+후처리가 실제 난도. "쉽다"로 뭉뚱그리지 않고 **각 단계를 독립 테스트 가능 단위**로 쪼갠다. 각 단위는 oar-ocr/Python PaddleOCR 이 **같은 fixture** 에 내는 출력을 골든벡터로 박아 단계별 회귀(0.976 baseline 대비)를 잡는다:
+
+1. **전처리**(resize/pad/normalize): det 입력 정규화(mean/std, /255). 골든: 알려진 이미지→텐서 일부 값.
+2. **det 후처리**: 확률맵(`[1,1,H,W]`)→threshold(0.3)→연결요소(imageproc)→**min-area rotated-rect(rotating calipers 직접 구현)**→**unclip(다각형 offset, ratio 1.5)**→박스. 골든: 합성 이미지의 기대 박스 개수/대략 좌표.
+3. **crop+rectify**: 회전 박스→perspective/affine warp 로 수평 정렬(oar-ocr 가 공짜 제공하던 부분; 직접 구현 필요). 골든: 회전 텍스트 fixture.
+4. **rec 전처리+추론**: crop→48×W 정규화→rec ONNX→`[1,T,C]` logits.
+5. **CTC greedy decode**: argmax per timestep→연속중복 제거→blank(인덱스 0 또는 dict 길이 위치, **PaddleOCR 규약 정확 매칭**) 제거→dict 인덱스→char. dict 길이(11,945) vs rec 출력 클래스(11,947) 정합 + **인덱스 bounds-check**(잘못된 dict 길이/빈 줄 방어). 골든: 알려진 logit→문자열.
+6. **box reading-order**: 상→하, 좌→우 정렬(가로쓰기 전제; 세로/회전 페이지는 비범위).
+
+각 단계 divergence 를 end-to-end 가 아니라 단위에서 잡는다(M1 권고).
+
+## Config
+
+`OcrCfg`(`kebab-config/src/lib.rs:343`)에 `engine` 필드 **이미 존재**(기본 `"ollama-vision"`). 변경:
+
+- `engine` 값에 `"paddle-onnx"` 추가(문서화). 기본값은 **당장 바꾸지 않음**(default 변경은 별도 결정 — 아래 "기본 엔진" 참조).
+- 신규(선택) 필드: `det_model` / `rec_model` / `dict` 경로 override(미지정 시 자동 다운로드 캐시 경로). `score_thresh`(기본 0.3), `unclip_ratio`(기본 1.5) 는 고급 튜닝용(기본값 고정, 노출 최소).
+- `pdf.ocr` 도 동일 `engine` 분기 적용(같은 trait).
+
+### 모델 배포 — 결정 C: kebab 와 함께 번들 (HF 미사용, 사용자 확정 2026-06-04)
+
+제3자(HF) 호스팅 의존 제거. 변환본(det 4.7MB + korean rec 13MB + dict ≈ **17MB**)을 kebab 자체에 번들. **구체 기법은 plan 에서 택1**(모두 HF/외부 네트워크 0):
+
+- **C-1 바이너리 임베드(`include_bytes!`)**: 모델을 바이너리에 박음. 진정한 single-binary·완전 오프라인·재현성 100%. 비용: 릴리스 바이너리 +17MB, 그리고 dev/test 빌드마다 17MB 링크 부담 → **release feature(`bundled-ocr-models`) 게이트**로 dev 빌드 제외 가능. 로컬-first 철학 최적합.
+- **C-2 repo 벤더링**: `assets/paddleocr-onnx/`(git 또는 git-LFS) 에 두고 빌드 시 `OUT_DIR` 복사 또는 런타임 상대경로. 바이너리 비대 회피하나 배포 시 파일 동반 필요.
+- **C-3 gitea 릴리스 에셋 + 첫 실행 다운로드**: `gitea-release --asset` 로 첨부, 첫 실행 시 릴리스 URL 에서 `model_dir/paddleocr-onnx/` 로 받음. 바이너리 lean 하나 첫 실행 시 gitea 네트워크 필요(에어갭 불가) — 로컬-first 와 약간 상충.
+
+**권장 = C-1(release feature 게이트)**: 오프라인·재현성·single-binary 가 kebab 정체성과 가장 정합. plan 에서 빌드/링크 영향 측정 후 확정.
+
+- **무결성**: 임베드(C-1)면 빌드 시점 고정이라 별도 해시 불요(바이너리=정본). C-2/C-3 면 blake3 pin 필수.
+- **라이선스**: PP-OCRv5 가중치 Apache-2.0 — 재배포 가능. 번들에 NOTICE 동반.
+- **오프라인**: C-1 완전 오프라인. config override(`det_model`/`rec_model`/`dict`)로 로컬 모델 교체 항상 가능.
+
+## 엔진 선택 (kebab-app 팩토리)
+
+현재 `OllamaVisionOcr` 하드코딩(`kebab-app/src/lib.rs:360`(image), `379`(pdf)). 변경:
+
+```rust
+let ocr_engine: Option<Box<dyn OcrEngine>> = if cfg.image.ocr.enabled {
+    match cfg.image.ocr.engine.as_str() {
+        "ollama-vision" => Some(Box::new(OllamaVisionOcr::new(cfg)?)),
+        "paddle-onnx"   => Some(Box::new(OnnxPaddleOcr::new(cfg)?)),
+        other => bail!("unknown image.ocr.engine: {other}"),
+    }
+} else { None };
+```
+
+- `ImagePipeline.ocr_engine` 를 `Option<&'a dyn OcrEngine>` 로(현재 구체타입 `&OllamaVisionOcr`).
+- pdf 경로 동일. `apply_ocr`/`apply_ocr_to_pdf_pages` 는 이미 `&dyn OcrEngine` 받음 → 변경 불필요.
+- `OnnxPaddleOcr` 는 한 번 생성(모델 1회 로드) 후 ingest 전체에서 재사용(PoC 모델로드 58ms, 무시 가능).
+
+## 버전/재색인 cascade
+
+OCR 엔진 변경 시 **영향 자산 자동 재색인**되어야 함(v0.26.2 메커니즘). 현재 `ingest_config_signature`(`kebab-app/src/lib.rs:3036` 부근)의 image/pdf 브랜치는 `|ocr:1:{ocr.model}` 만 서명.
+
+**C3 (필수, 권장 아님)**: paddle-onnx 브랜치에서 `model`("gemma4:e4b" 기본) 은 **미사용** — 실제 모델 정체성은 det/rec/dict + engine_version 에 있음. 따라서:
+- 서명을 `|ocr:1:{engine}:{engine_version}` 로(엔진 + 모델/dict 식별자). `engine_version()`(spec 의 model+dict blake3 해시 포함, 라인 47)을 **반드시** 서명에 사용.
+- 이유: ① `engine="ollama-vision"→"paddle-onnx"` 전환 시 model 이 기본값 그대로면 `{model}` 만으론 서명 불변 → **재색인 안 됨**(silent stale index, v0.26.2 가 없애려던 바로 그 버그). ② 모델 재변환/dict 수정 시 engine_version 변화로 재색인 트리거.
+- 단위테스트(필수): (a) `ollama-vision`↔`paddle-onnx` 동일 model → 서명 다름. (b) 동일 engine, engine_version 다름 → 서명 다름. (c) 무관 설정(search 등) → 서명 불변.
+
+## 기본 엔진 (default) — 별도 결정
+
+본 spec 은 `paddle-onnx` 를 **선택 가능**하게만 한다. kebab 의 `image.ocr.engine` **기본값을 `paddle-onnx` 로 바꿀지**는 후속 결정:
+- 바꾸면: 신규 사용자/기본 동작 변화 + 모델 다운로드 기본화. 강력하나 영향 큼.
+- v1 은 기본 `ollama-vision` 유지, opt-in `paddle-onnx`. 도그푸딩 후 기본 전환을 별 PR 로. (사용자 본인 config 는 즉시 `paddle-onnx`.)
+
+## 에러 처리 (M3 — 명시 매트릭스)
+
+배치 ingest 가 미지의 사용자 스캔을 돈다. 각 케이스 동작 확정:
+
+| 케이스 | 동작 | 근거 |
+|---|---|---|
+| 모델 다운로드 실패 | 엔진 생성 시 **fail-fast**(Ollama 와 동일, `lib.rs:360`) | 색인 시작 전 차단 |
+| blake3 불일치 | fail-fast + 사유 | 무결성 |
+| 디코드 불가 이미지 | **자산 skip + provenance 노트**(ingest 중단 X) | 기존 `apply_ocr` "skip vs surface" 계약(`ocr.rs:75`) |
+| det 0 박스(빈 이미지 등) | **성공, `OcrText{joined:"", regions:[]}`**(에러 아님) | Ollama 빈줄 동작(`ocr.rs:290`) 미러 |
+| rec 빈 출력(한 박스) | 그 박스 skip, 나머지 진행 | |
+| 박스 폭증(노이즈 스캔) | **`max_boxes` 상한**(기본 예: 1000) 초과분 절단 + 로그 | 메모리/지연 cliff 방지 |
+| dict 길이 ≠ rec 클래스 | 생성 시 에러(정합 검증) | bounds-check |
+
+ort `Session` 은 생성 후 1회 로드·재사용. ingest 는 현재 직렬(`lib.rs:460`, rayon 없음)이라 동시접근 없음 — 단 `OcrEngine: Send+Sync` 유지(미래 병렬화 대비, rc.9 Session Send/Sync 확인은 plan).
+
+## 검증 기준
+
+- `cargo clippy --workspace --all-targets -j 8 -- -D warnings` 0.
+- `cargo test -p kebab-parse-image -p kebab-app -j 8` 통과(touched 크레이트; `kebab-parse-image` 단독 빌드가 download-binaries 로 링크되는지 포함).
+- 신규 단위테스트:
+  - 단계별 골든벡터(전처리/det후처리/CTC/박스정렬) — baseline 0.976 대비 단계 회귀 감지.
+  - OnnxPaddleOcr e2e: 합성 한/영 fixture → **CER ≤ 0.05**(=문자정확도 ≥95%), bbox>0. (단 합성 fixture 는 실코퍼스 회귀 미보장 → 도그푸딩 병행.)
+  - CTC decode: 알려진 logit→문자열(blank/중복 제거, bounds-check).
+  - 엔진 팩토리: `engine="paddle-onnx"`→OnnxPaddleOcr, 미지 값 에러.
+  - 서명(C3): 위 (a)(b)(c) 케이스.
+  - config override(`det_model`/`rec_model`/`dict`) 가 실제 사용됨 + **`--config` facade 스레딩**(CLAUDE.md facade rule, P3-5/P4-3 회귀 전례) — `OnnxPaddleOcr::new(cfg, …)` 가 explicit Config 받음.
+- 회귀 가드: `engine="ollama-vision"`(기본) 경로 — 팩토리 리팩터(구체타입→`&dyn`) 후에도 **출력 동일** 핀하는 테스트.
+- 스모크: `engine="paddle-onnx"` 이미지 ingest → OCR 텍스트 FTS5 hit. 큰 페이지 CPU <5초.
+- 도그푸딩: 사용자 실제 이미지/책 스캔 정확도·속도(HOTFIXES + release notes).
+
+## 의존성 규칙 (design §8)
+
+`kebab-parse-image` allowed: kebab-core, kebab-config, serde, image, tracing, thiserror(task p6-2). 추가: `ort`(workspace, features `["ndarray","download-binaries"]`), `ndarray`(workspace), `imageproc`. **clipper2 미추가**(C++ FFI 회피 — unclip pure-Rust 직접). **hf-hub 미추가**(결정 C: 모델 번들, 외부 다운로드 0). **금지 유지**: kebab-store-*/embed-*/llm-* 미import. UI 크레이트 영향 없음.
+
+## 비범위
+
+- **OCR 텍스트→임베딩 갭**(현재 OCR 은 FTS5 lexical 전용, 벡터 미포함). 사용자 "OCR 모델만 먼저" → 별도 작업.
+- **caption** 은 gemma 유지([[project_llm_default]]).
+- **GPU provider**(ort CUDA/CoreML): CPU 로 충분(2.75초). 후속 옵션.
+- **기본 엔진 전환**(default `paddle-onnx`): 도그푸딩 후 별 PR.
+- 다국어 dict 동적 전환(현재 korean dict = 한+영+숫자+기호 11,945자로 한/영 충분).
+
+## 잔여 노트 (critic minors)
+
+- **max_pixels(m1)**: 기존 `[256,4096]` clamp 은 VLM 프롬프트 비용 기준. det/rec 엔진은 비용이 latency 라 trade-off 다름. v1 은 기본 1600 **유지(의도적)** — PoC 에서 1600 대 원본 정확도 차 미미, 속도 이점. plan 에서 paddle-onnx 전용 기본 재검토 가능.
+- **config 마이그레이션(m3)**: 신규 키(`det_model` 등)는 serde default 로 forward-compat(기존 파일 무수정 로드). `kebab config migrate`(#198) 가 주석/순서 보존하며 신규 키 추가 — migration 핸들링 불필요(serde default), 단 init 템플릿에 신규 키 노출.
+- **per-region confidence(open q)**: Ollama 는 region confidence 상수 1.0, paddle-onnx 는 실제 score. `OcrRegion` 형태 불변이라 wire 호환(값만 의미있어짐) — release note 1줄.
+- **세로/회전 페이지**: 비범위(가로쓰기 reading-order 전제). 회전 박스 rectify 는 지원하나 페이지 전체 세로조판은 미지원 명시.
+
+## 버전/문서
+
+- feature(신규 engine 값 + 동작) → **minor bump**.
+- README(Configuration: `image.ocr.engine`, 모델 첫 다운로드 안내), docs/SMOKE(config 예시), HANDOFF 1줄, docs/ARCHITECTURE(새 OCR 백엔드 추가 시 그래프/결정), HOTFIXES dated entry(도그푸딩 evidence). wire schema 불변(OcrText 내부, `--json` 표면 동일).
--- a/tasks/HOTFIXES.md
+++ b/tasks/HOTFIXES.md
@@ -14,6 +14,88 @@ historical contract that was implemented; this file accumulates the
 deltas so phase 5+ readers can find the live behavior without diffing
 git history.

+## 2026-06-04 — PP-OCRv5 ONNX Rust 네이티브 OCR 엔진 (v0.27.0)
+
+**무엇을 추가했나.** 이미지 OCR 에 두 번째 백엔드 `paddle-onnx` 를 붙였다. 기존 `ollama-vision`
+(원격 vision LM, 이미지당 ~50초)은 default 로 유지하고, `[image.ocr] engine = "paddle-onnx"` 로
+PP-OCRv5(검출 DBNet + 인식 CTC) ONNX 모델을 `ort`(=2.0.0-rc.9) 로 **in-process** 실행한다 —
+Python 런타임/원격 호출 없이 큰 페이지 CPU <4초. `OcrEngine` trait 의 두 번째 구현
+`OnnxPaddleOcr`(`crates/kebab-parse-image/src/paddle_onnx.rs`), 팩토리는
+`kebab-app::build_image_ocr_engine`/`build_pdf_ocr_engine` (`match engine`). 검출 후처리
+(min-area rect = rotating calipers, unclip = polygon offset)는 clipper2/OpenCV 없이 pure-Rust.
+
+**T11 e2e 에서 발견·수정한 핵심 버그 (unclip).** 첫 실측 CER 이 0.26(게이트 0.05) 으로 크게
+초과. 단계 골든(`crates/kebab-parse-image/tests/golden/`) 와 prediction dump 로 국소화한 결과
+`unclip_rect` 가 corner 를 centroid 기준 **방사(radial) 확장**하고 있었다. 텍스트 박스는
+wide/short(예 586×15)라 대각선이 거의 수평 → 방사 확장 시 corner 가 수평으로만 ~11px 움직이고
+**세로로는 거의 안 커져** 글자 윗/아랫부분이 잘렸다(ㄷ→ㄴ 로 `다`→`나`, ascender 손실).
+PaddleOCR pyclipper 처럼 **edge 별로 바깥으로 offset**(width·height 각각 2·distance 증가) 하도록
+rect 자체 (u,v) 축 기준 확장으로 재작성. 결과: mean gate CER **0.2585 → 0.0049**
+(clean_paragraph/korean_heavy/numbers_table/tech_terms = 0.0), PoC 0.024 baseline 보다 우수.
+큰 페이지 3.9초 < 5초 게이트. **교훈**: 회전 사각형 unclip 은 방사 확장이 아니라 polygon edge
+offset 이어야 한다.
+
+**Config / 서명 cascade.** `[image.ocr]` 에 `det_model`/`rec_model`/`dict`(Option, override) +
+`score_thresh`(0.3)/`unclip_ratio`(1.5)/`max_boxes`(1000) serde-default 필드 + `KEBAB_IMAGE_OCR_*`
+env 추가(기존 config 무수정 로드 — forward-compat). `ingest_config_signature` 의 image/pdf 브랜치를
+`|ocr:1:{model}` → `|ocr:1:{engine}:{engine_version}` 로 바꿔 engine 전환(ollama↔paddle) 또는
+모델 변경 시 영향 자산 자동 재색인. paddle engine_version 은 모델 3-asset blake3 를 **per-process
+1회만** 계산(triple 키 memo) — 자산마다 17MB 재해시 회피.
+
+**모델 배포.** ONNX 2개(det 4.7MB / rec 13MB) + dict + NOTICE 를 `crates/kebab-parse-image/
+assets/paddleocr-onnx/` 에 둔다(Git LFS). 테스트는 `KEBAB_IMAGE_OCR_MODEL_DIR`(기본 = 번들 dir)
+에서 로드, e2e(`tests/paddle_e2e.rs`)는 모델/fixture 부재 시 깨끗이 skip(CI green). 자세한 설계:
+spec/plan `docs/superpowers/{specs,plans}/2026-06-04-rust-native-ocr-*.md`.
+
+## 2026-06-03 — ingest 출력 영향 설정 변경 시 영향 자산 자동 재색인 (v0.26.2)
+
+**무엇이 깨졌나.** `[image.ocr]` / `[image.caption]` 를 off→색인→on 으로 바꿔도 증분
+skip(`try_skip_unchanged`, `kebab-app/src/lib.rs`)이 그 이미지를 "Unchanged" 로 건너뛰어
+재색인이 안 됐다. 더 일반적으로, skip 판정은 자산 내용(blake3) + `parser_version` +
+`chunker_version` + `embedding_version` 만 비교하는데, **ingest 산출물을 바꾸는 다른 설정들**
+(청킹 파라미터, OCR/caption, pdf.ocr, `[ingest.code]` 옵션)이 이 셋 중 어디에도 반영되지
+않아, 변경해도 재색인이 트리거되지 않았다. 사용자 요구: OCR/caption 뿐 아니라 **ingest 출력에
+영향 주는 모든 설정**이 변경되면 영향 자산이 자동 재색인.
+
+**무엇이 바뀌었나 (내부 skip 판정 정정 — 결과 포맷·CLI·wire 불변, patch).**
+
+- 신규 헬퍼 `ingest_config_signature(config, media_type) -> String` — 그 자산 타입의
+  **ingest 산출물에 영향 주는 설정만** 결정적으로 직렬화. 공통(전 타입): `[chunking]`
+  target_tokens/overlap_tokens/respect_markdown_headings/chunker_version. image: + ocr(enabled,
+  +model) + caption(enabled, +prompt_template_version). pdf: + pdf.ocr(enabled||always_on 이면
+  enabled/always_on/model). code: + `[ingest.code]` 7개 필드. markdown: 공통만.
+- 각 ingest 경로(md/image/pdf/code)의 effective parser_version 을
+  `format!("{base}|{signature}")` composite 로 만들어 (a) `try_skip_unchanged` 비교값,
+  (b) **persist 전 `canonical.parser_version` override** — 두 값이 같은 함수에서 나오므로
+  설정 변경 시 다음 run 비교가 mismatch → 영향 자산만 자동 재색인.
+- **doc_id 는 손대지 않음**: base parser_version(extractor 상수)으로 계속 파생 →
+  설정 변경에도 doc_id 안정(orphan churn 회피). composite 는 비교/저장 필드에만.
+- **제외(재색인 트리거 X)**: search/rag/nli/ui/logging/storage/workspace + 산출 무관
+  런타임 파라미터(max_pixels/languages/*_timeout_secs). "그 값이 바뀌면 색인되는
+  chunk/embedding 내용이 달라지는가" 기준. 과도 무효화 회피.
+- code 의 Tier-3 fallback 문서는 의도적으로 bare `"none-v1"` sentinel 유지(skip 의
+  `stored_is_tier3_fallback` bypass 가 정확히 그 문자열에 의존) — composite 는 정상 outcome 에만.
+
+**업그레이드 1회 효과.** 기존 doc 의 저장 parser_version(상수)이 새 composite 와 달라,
+업그레이드 후 첫 `kebab ingest` 에서 **전 자산이 현재 설정대로 1회 재색인**된다(force 불필요).
+마크다운/코드도 1회 재청킹되나 embedding 은 V012 derived-cache 히트라 재임베딩 비용은 작다.
+`--force-reingest` 는 전체 강제용으로 그대로.
+
+**도그푸딩 evidence (release 바이너리, Ollama down — OCR 호출은 Lenient 실패).**
+이미지 1장, `[image.ocr] enabled=false` 색인 → New=1. config 에서 `enabled=true` 로 변경 후
+`kebab ingest`(force 없이) → **Updated=1**(재색인, errors=0). 동일 config 재실행 → **Unchanged=1**
+(불필요 재색인 0). 저장된 parser_version =
+`image-meta-v1|chunk:500:80:true:md-heading-v1|ocr:1:gemma4:e4b|cap:0`(base 보존 + OCR on 반영).
+
+**테스트.** `kebab-app/src/lib.rs::ingest_config_signature_tests`(8 단위: 결정성, 청킹=전타입,
+이미지 ocr/caption 토글=이미지만, pdf.ocr=pdf만, code 옵션=코드만, search/rag/ui·런타임 파라미터
+불변 회귀가드) + `kebab-app/tests/config_invalidation.rs`(4 end-to-end: 동일 config=전 skip,
+청킹 변경=md+code 재색인, `[ingest.code]` 변경=코드만, search 변경=재색인 0). 기존 skip 테스트
+회귀 0(parser_version exact assert 는 base 접두사 비교로 갱신 — code_ingest_smoke/pdf_pipeline).
+
+spec/plan: `docs/superpowers/specs/2026-06-03-ocr-toggle-invalidation-spec.md` /
+`…/plans/2026-06-03-config-invalidation-plan.md`.
+
 ## 2026-06-03 — ingest 진행 로그 개선: 파일명·phase·heartbeat·slowest 요약 (v0.26.1)

 **무엇을 왜 추가했나.** arctic 도그푸딩 중 이미지/PDF 혼재 + OCR/caption on 볼트에서
Author	SHA1	Message	Date
altair823	898cdaa043	docs(config): v3 스키마 재편 설계 + 구현 계획	2026-06-04 12:25:49 +00:00
altair823	01a17acd3f	Merge pull request 'feat(ocr): PP-OCRv5 ONNX Rust 네이티브 OCR 엔진' (#206 ) from feat/rust-native-ocr into main Reviewed-on: #206	2026-06-04 09:24:37 +00:00
altair823	f3a7222ec5	fix(ocr): PR #206 round-1 리뷰 반영 — 골든 CI 테스트 + PDF 튜닝 문서 + threshold const + mutex 복구 - [MEDIUM] 골든 CI 단위테스트 2건 추가: ctc_greedy_decode_golden (argmax_idx one-hot → decoded 문자열 검증), det_box_score_golden (box_score/unclip_rect golden corner 검증). 모델/ONNX 불요, CI 상주. ctc_greedy_decode를 자유 함수(ctc_greedy_decode_with_dict)로 추출하여 테스트 가능하게 함. - [MEDIUM] PDF paddle 튜닝 비대칭 문서화: build_pdf_ocr_engine에 paddle-onnx가 image.ocr.* 사용(pdf.ocr.* 아님) 이유 명시 + PdfOcrCfg.engine 필드 doc 갱신. - [MEDIUM] DBNet 이진화 매직넘버 0.3 → DET_BIN_THRESH const 추출 + score_thresh 기본값 느슨한 이유 1줄 주석. - [LOW] Mutex poison 복구: det/rec .expect("poisoned") → .unwrap_or_else(PoisonError::into_inner). 자산 panic이 ingest abort 안 되도록. - [LOW] DetBox.score dead field 제거 (box_score 결과는 필터에만 사용, 저장 불요). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-06-04 09:13:27 +00:00
altair823	3d5bb599e3	feat(ocr): bundle PP-OCRv5 ONNX models (det 4.7MB + rec 13MB) paddle-onnx engine assets — committed as plain binary blobs (git-lfs not installed on this host; see .gitattributes for the LFS migration recipe). NOTICE (Apache-2.0) + korean_dict.txt already tracked. Loaded by default from this dir or KEBAB_IMAGE_OCR_MODEL_DIR. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-06-04 08:36:34 +00:00
altair823	375a0693e4	chore(ocr): T11/T12 — clippy clean + docs + v0.27.0 bump T11: fix 12 clippy lints in paddle_onnx.rs/paddle_e2e.rs (doc overindent, finish_non_exhaustive, map_or_else, RangeInclusive::contains, cast_lossless, is_some_and, usize::from). Full-workspace clippy -D warnings = 0. Smoke (paddle-onnx, real binary): clean_paragraph OCR verbatim-correct, real per-region confidence (0.99/0.96/0.95), FTS5 lexical hit on Korean(검색)+ English(embedding), parser_version folds \|ocr:1:paddle-onnx:<ver>. Big page <4s inference (5.6s ingest incl. one-time session load). T12: README [image.ocr].engine + ARCHITECTURE OCR row + SMOKE paddle-onnx config + HANDOFF + HOTFIXES dated entry. Workspace version 0.26.2 → 0.27.0 (minor: new engine value + config keys). .gitattributes: onnx as plain blobs (no git-lfs). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-06-04 08:36:19 +00:00
altair823	8cc4e6d563	fix(ocr): T10/T11 — unclip edge-offset (CER 0.26→0.005) + e2e gate + error tests Root cause found at T11 e2e: unclip_rect pushed corners radially from the centroid. For a wide/short text box the diagonal is near-horizontal, so the box barely grew in height and clipped character tops (ㄷ→ㄴ, 다→나). Rewrote unclip as a proper per-edge polygon offset along the rect's own (u,v) axes — height and width each grow by 2*distance, matching PaddleOCR pyclipper. Result (synthetic-ocr-bench, real inference): mean gate CER 0.2585 → 0.0049 (clean_paragraph/korean_heavy/numbers_table/tech_terms = 0.0), beating the 0.976 PoC baseline. Big page 3.9s < 5s. T10: dict-length-mismatch construction error + undecodable-bytes recognize error. T11 e2e: tests/paddle_e2e.rs CER<=0.05 gate (skips cleanly when assets absent). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-06-04 08:22:47 +00:00
altair823	901416d8e9	feat(ocr): T7-T9 — config overrides + engine factory + signature cascade T7: OcrCfg gains det_model/rec_model/dict overrides + score_thresh/ unclip_ratio/max_boxes (serde default, KEBAB_IMAGE_OCR_* env). OnnxPaddleOcr::new threads them via ModelPaths::from_config. T8: build_image_ocr_engine / build_pdf_ocr_engine factories return Box<dyn OcrEngine>; match on engine string (ollama-vision\|paddle-onnx\|err). ImagePipeline.ocr_engine + pdf_ocr_engine signatures switched to &dyn OcrEngine. OcrEngine gains model() for the progress label. T9: ingest_config_signature image/pdf branches emit \|ocr:1:{engine}:{engine_version} (memoized blake3 per asset-triple, m3-safe). Unit tests (a)(b)(c) added. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-06-04 08:15:30 +00:00
altair823	b706e3e88c	feat(ocr): T2-T6 OnnxPaddleOcr core engine — det/rec ONNX + DBNet postproc + CTC PP-OCRv5 ONNX OCR engine on the pinned ort rc.9 (no Python, no oar-ocr dep). Implements the recognize() pipeline end-to-end (compiles + unit-tested): - T2: OnnxPaddleOcr skeleton, OcrEngine impl, det/rec Session loaded once (Mutex-wrapped → Send+Sync), engine_version = blake3(det+rec+dict) cached once at construction, dict bounds-check (11945 lines vs 11947 rec classes). - T2 preproc: det ImageNet mean/std NCHW + limit_side_len 960 → ×32 round (golden 192x900→896x192 pinned); rec height-48 keep-aspect, (x-0.5)/0.5. - T3 det postproc: threshold 0.3 → imageproc contours → min-area rect via pure-Rust rotating calipers + convex hull → mean-prob box-score filter → pure-Rust unclip(ratio 1.5). No clipper2/OpenCV. - T4 crop+rectify: corner ordering + bilinear perspective warp to horizontal. - T5 rec+CTC: greedy decode with the T0a-confirmed mapping (idx0=blank, 1..=11945=dict[idx-1], 11946=space), rec-class bounds-check. - T6 assembly: reading-order OcrText with per-region bbox + real confidence. Unit tests (4 pass): det_target_dims golden, convex hull, min-area rect, unclip expansion. Large *.onnx assets stay untracked pending T12 LFS decision. Remaining: T7 config overrides, T8 factory (4 sites), T9 signature cascade, T10 error matrix, T11 gates (clippy/e2e CER), T12 docs+bump+PR. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-06-04 07:52:39 +00:00
altair823	8f8d3a4100	feat(ocr): T0a/T0/T1 — golden harness(CTC blank=0 도출) + deps(ort rc.9) + dict/NOTICE T0a: onnxruntime 직접 골든 하네스 → CTC blank/dict 매핑 경험 확정(gt CER 0.000). T0: 모델 번들 dict+NOTICE(.onnx 는 T12 LFS 결정까지 워크트리 보관). T1: ort(download-binaries)+imageproc 추가, cargo tree ort rc.9 단일 확인.	2026-06-04 07:43:53 +00:00
altair823	75a543ff69	docs(ocr): PP-OCRv5 ONNX Rust 네이티브 OCR spec + plan	2026-06-04 07:31:03 +00:00
altair823	a283e56c5c	Merge pull request 'fix(ingest): ingest 설정 변경 시 영향 자산 자동 재색인' (#205 ) from fix/ingest-config-invalidation into main Reviewed-on: #205	2026-06-03 14:33:18 +00:00
altair823	47ef6532f7	chore(release): v0.26.2 — ingest 설정 변경 자동 재색인 + 문서 - Cargo.toml workspace version 0.26.1 → 0.26.2 (+Cargo.lock cascade). 결과 포맷·CLI·wire 불변(내부 skip 판정 정정) → patch (CLAUDE.md §Versioning). - tasks/HOTFIXES.md dated entry: 일반화 + 업그레이드 1회 재색인 안내 + 도그푸딩 evidence. - HANDOFF.md 1줄. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-06-03 14:14:23 +00:00
altair823	03b0745e9d	test(ingest): config invalidation e2e + parser_version assert 갱신 - config_invalidation.rs(신규): 동일config=전skip / 청킹변경=md+code재색인 / [ingest.code]변경=코드만 / search변경=재색인0 (회귀가드) end-to-end. - code_ingest_smoke / pdf_pipeline: 저장 parser_version 이 이제 "{base}\|{sig}" composite 라, exact assert 를 base 접두사(split('\|').next()) 비교로 갱신. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-06-03 14:14:15 +00:00
altair823	e7cb20990a	feat(ingest): ingest 설정 변경 시 영향 자산 자동 재색인 (signature 폴딩) ingest 산출에 영향 주는 설정(청킹/이미지 OCR·caption/pdf.ocr/[ingest.code])의 결정적 서명을 effective parser_version 에 폴딩 → 변경 시 --force-reingest 없이 영향 자산만 자동 재색인. - ingest_config_signature(config, media_type): per-type 산출-영향 설정만 직렬화. 비산출 설정(search/rag/ui/log + max_pixels/languages/timeout)은 제외. - effective_parser_version(config, asset, base) = "{base}\|{signature}". - md/image/pdf/code 경로: composite 를 (a) try_skip_unchanged 비교값, (b) persist 전 canonical.parser_version override 에 사용. - doc_id 는 base parser_version 으로 계속 파생 → 설정 변경에도 안정(orphan churn 회피). - code Tier-3 fallback 은 bare "none-v1" sentinel 유지(skip bypass 의존). - 단위테스트 8: 결정성/청킹=전타입/이미지·pdf·code 토글/무관설정 회귀가드. spec: docs/superpowers/specs/2026-06-03-ocr-toggle-invalidation-spec.md Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-06-03 14:14:06 +00:00
altair823	bebf6e4ac7	docs(spec): ingest 설정 변경 자동 재색인 spec + plan 증분 skip 이 OCR/caption·청킹·코드 등 ingest 산출 영향 설정 변경을 못 잡아 재색인 안 되던 갭 일반화 수정. per-asset-type "ingest config signature" 를 effective parser_version 에 폴딩 → 영향 설정 변경 시 영향 자산만 자동 재색인. patch(0.26.2). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-06-03 13:40:02 +00:00