Merge pull request 'chore(release): bump version 0.17.2 → 0.18.0 + cut fb-41 multi-hop' (#182) from chore/v0-18-0-cut into main

Reviewed-on: #182

Cargo.lock

@@ -4127,7 +4127,7 @@ dependencies = [
 
 [[package]]
 name = "kebab-app"
-version = "0.14.0"
+version = "0.18.0"
 dependencies = [
  "anyhow",
  "base64 0.22.1",
@@ -4142,6 +4142,7 @@ dependencies = [
  "kebab-embed-local",
  "kebab-llm",
  "kebab-llm-local",
+ "kebab-nli",
  "kebab-normalize",
  "kebab-parse-code",
  "kebab-parse-image",
@@ -4172,12 +4173,13 @@ dependencies = [
 
 [[package]]
 name = "kebab-chunk"
-version = "0.14.0"
+version = "0.18.0"
 dependencies = [
  "anyhow",
  "blake3",
  "kebab-core",
  "kebab-normalize",
+ "kebab-parse-code",
  "kebab-parse-md",
  "serde_json",
  "serde_json_canonicalizer",
@@ -4188,7 +4190,7 @@ dependencies = [
 
 [[package]]
 name = "kebab-cli"
-version = "0.14.0"
+version = "0.18.0"
 dependencies = [
  "anyhow",
  "clap",
@@ -4209,7 +4211,7 @@ dependencies = [
 
 [[package]]
 name = "kebab-config"
-version = "0.14.0"
+version = "0.18.0"
 dependencies = [
  "anyhow",
  "dirs 5.0.1",
@@ -4224,7 +4226,7 @@ dependencies = [
 
 [[package]]
 name = "kebab-core"
-version = "0.14.0"
+version = "0.18.0"
 dependencies = [
  "anyhow",
  "blake3",
@@ -4238,7 +4240,7 @@ dependencies = [
 
 [[package]]
 name = "kebab-embed"
-version = "0.14.0"
+version = "0.18.0"
 dependencies = [
  "anyhow",
  "blake3",
@@ -4252,7 +4254,7 @@ dependencies = [
 
 [[package]]
 name = "kebab-embed-local"
-version = "0.14.0"
+version = "0.18.0"
 dependencies = [
  "anyhow",
  "fastembed",
@@ -4265,7 +4267,7 @@ dependencies = [
 
 [[package]]
 name = "kebab-eval"
-version = "0.14.0"
+version = "0.18.0"
 dependencies = [
  "anyhow",
  "kebab-app",
@@ -4284,7 +4286,7 @@ dependencies = [
 
 [[package]]
 name = "kebab-llm"
-version = "0.14.0"
+version = "0.18.0"
 dependencies = [
  "anyhow",
  "kebab-core",
@@ -4293,7 +4295,7 @@ dependencies = [
 
 [[package]]
 name = "kebab-llm-local"
-version = "0.14.0"
+version = "0.18.0"
 dependencies = [
  "anyhow",
  "kebab-config",
@@ -4310,7 +4312,7 @@ dependencies = [
 
 [[package]]
 name = "kebab-mcp"
-version = "0.14.0"
+version = "0.18.0"
 dependencies = [
  "anyhow",
  "kebab-app",
@@ -4326,9 +4328,24 @@ dependencies = [
  "tracing",
 ]
 
+[[package]]
+name = "kebab-nli"
+version = "0.18.0"
+dependencies = [
+ "anyhow",
+ "hf-hub",
+ "kebab-config",
+ "ndarray",
+ "ort",
+ "serde",
+ "tempfile",
+ "tokenizers",
+ "tracing",
+]
+
 [[package]]
 name = "kebab-normalize"
-version = "0.14.0"
+version = "0.18.0"
 dependencies = [
  "anyhow",
  "kebab-core",
@@ -4343,7 +4360,7 @@ dependencies = [
 
 [[package]]
 name = "kebab-parse-code"
-version = "0.14.0"
+version = "0.18.0"
 dependencies = [
  "anyhow",
  "gix",
@@ -4353,6 +4370,8 @@ dependencies = [
  "time",
  "tracing",
  "tree-sitter",
+ "tree-sitter-c",
+ "tree-sitter-cpp",
  "tree-sitter-go",
  "tree-sitter-java",
  "tree-sitter-javascript",
@@ -4364,7 +4383,7 @@ dependencies = [
 
 [[package]]
 name = "kebab-parse-image"
-version = "0.14.0"
+version = "0.18.0"
 dependencies = [
  "ab_glyph",
  "anyhow",
@@ -4388,7 +4407,7 @@ dependencies = [
 
 [[package]]
 name = "kebab-parse-md"
-version = "0.14.0"
+version = "0.18.0"
 dependencies = [
  "anyhow",
  "kebab-core",
@@ -4405,7 +4424,7 @@ dependencies = [
 
 [[package]]
 name = "kebab-parse-pdf"
-version = "0.14.0"
+version = "0.18.0"
 dependencies = [
  "anyhow",
  "blake3",
@@ -4418,7 +4437,7 @@ dependencies = [
 
 [[package]]
 name = "kebab-parse-types"
-version = "0.14.0"
+version = "0.18.0"
 dependencies = [
  "kebab-core",
  "serde",
@@ -4426,13 +4445,14 @@ dependencies = [
 
 [[package]]
 name = "kebab-rag"
-version = "0.14.0"
+version = "0.18.0"
 dependencies = [
  "anyhow",
  "blake3",
  "kebab-config",
  "kebab-core",
  "kebab-llm",
+ "kebab-nli",
  "kebab-search",
  "kebab-store-sqlite",
  "regex",
@@ -4447,7 +4467,7 @@ dependencies = [
 
 [[package]]
 name = "kebab-search"
-version = "0.14.0"
+version = "0.18.0"
 dependencies = [
  "anyhow",
  "globset",
@@ -4466,7 +4486,7 @@ dependencies = [
 
 [[package]]
 name = "kebab-source-fs"
-version = "0.14.0"
+version = "0.18.0"
 dependencies = [
  "anyhow",
  "blake3",
@@ -4485,7 +4505,7 @@ dependencies = [
 
 [[package]]
 name = "kebab-store-sqlite"
-version = "0.14.0"
+version = "0.18.0"
 dependencies = [
  "anyhow",
  "blake3",
@@ -4506,7 +4526,7 @@ dependencies = [
 
 [[package]]
 name = "kebab-store-vector"
-version = "0.14.0"
+version = "0.18.0"
 dependencies = [
  "anyhow",
  "arrow",
@@ -4530,7 +4550,7 @@ dependencies = [
 
 [[package]]
 name = "kebab-tui"
-version = "0.14.0"
+version = "0.18.0"
 dependencies = [
  "anyhow",
  "crossterm",
@@ -8531,6 +8551,26 @@ dependencies = [
  "tree-sitter-language",
 ]
 
+[[package]]
+name = "tree-sitter-c"
+version = "0.24.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a9b2eb57a55fed6b00812912e730b7a275cf4fe98bfd6a5d76263d4438371728"
+dependencies = [
+ "cc",
+ "tree-sitter-language",
+]
+
+[[package]]
+name = "tree-sitter-cpp"
+version = "0.23.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "df2196ea9d47b4ab4a31b9297eaa5a5d19a0b121dceb9f118f6790ad0ab94743"
+dependencies = [
+ "cc",
+ "tree-sitter-language",
+]
+
 [[package]]
 name = "tree-sitter-go"
 version = "0.25.0"

Cargo.toml

@@ -24,6 +24,7 @@ members = [
     "crates/kebab-tui",
     "crates/kebab-mcp",
     "crates/kebab-parse-code",
+    "crates/kebab-nli",
 ]
 
 [workspace.package]
@@ -31,7 +32,95 @@ edition       = "2024"
 rust-version  = "1.85"
 license       = "MIT OR Apache-2.0"
 repository    = "https://github.com/altair823/kebab"
-version       = "0.14.0"
+version       = "0.18.0"
+
+# pre-v0.18 workspace-wide cleanup: enable clippy::pedantic group with
+# intentional allow-list. The allowed lints are either cosmetic (doc style),
+# informational (function size), or carry intentional truncation we accept
+# (numeric casts in tokenizer/ONNX inputs, hash modular reduction, etc).
+[workspace.lints.clippy]
+pedantic = { level = "warn", priority = -1 }
+# Intentional u32 ↔ i64 casts in kebab-nli (ONNX i64 inputs from tokenizer u32 ids).
+# u64 ↔ usize across kebab-store-sqlite row counts. Wide truncation is auditable
+# at use site, not lint-wide.
+cast_possible_truncation = "allow"
+cast_possible_wrap       = "allow"
+cast_sign_loss           = "allow"
+cast_precision_loss      = "allow"
+# Doc markdown style is cosmetic; we run rustdoc on demand.
+doc_markdown            = "allow"
+missing_errors_doc      = "allow"
+missing_panics_doc      = "allow"
+# Informational only — splitting a long pipeline function isn't always cleaner.
+too_many_lines          = "allow"
+# `Foo::default()` is concise and idiomatic here; `<Foo as Default>::default()`
+# adds noise without surfacing intent.
+default_trait_access    = "allow"
+# Module name prefix on public items keeps the wire/log surface readable
+# (`refusal_reason::no_chunks` etc).
+module_name_repetitions = "allow"
+# We use `#[must_use]` deliberately on public results, not blanket.
+must_use_candidate      = "allow"
+# `String` arg sometimes signals "I'll consume this" — let signature decide.
+needless_pass_by_value  = "allow"
+# Idiomatic single-line bindings stay; let-else expansion isn't always clearer.
+manual_let_else         = "allow"
+# `use` after `let` is a common kebab pattern (scoped imports next to use site).
+items_after_statements  = "allow"
+# Naming pairs like `chunk_id` / `chunks_id` are intentional domain terms.
+similar_names           = "allow"
+# `iter.map(format!).collect::<String>()` is idiomatic when the per-element
+# string is genuinely independent — `fold` only wins on accumulation patterns.
+format_collect          = "allow"
+# Exhaustive `match` with explicit variant arms (vs `_`) catches future
+# variant additions at compile time (kebab core's `RefusalReason` pattern).
+match_wildcard_for_single_variants = "allow"
+# Copy types under `&self` keep call-site discipline; auto-deref noise > tiny perf gain.
+trivially_copy_pass_by_ref = "allow"
+# `unnecessary_wraps` flags helpers that could drop `Result`, but keeping the
+# Result allows future error variants without churning callers.
+unnecessary_wraps        = "allow"
+# NLI score / RRF fusion / similarity threshold comparisons are intentional —
+# floats live in the `[0, 1]` band and are compared with explicit thresholds.
+float_cmp                = "allow"
+# File-extension dispatch is keyed on ASCII conventions; case sensitivity
+# is part of the spec for `.md`, `.pdf`, etc.
+case_sensitive_file_extension_comparisons = "allow"
+# Config / opts structs intentionally bundle boolean flags (ingest options,
+# search modes, etc) — splitting them into enums would obscure the wire shape.
+struct_excessive_bools   = "allow"
+# `bytecount` crate would be a new dep just for one-off ASCII counts.
+naive_bytecount          = "allow"
+# `#[ignore]` annotations on tests document via the test name + nearby comment.
+ignore_without_reason    = "allow"
+# `format!` push patterns are a hot path for kebab-tui's progressive rendering;
+# `write!` rewrite needs a verified-equal benchmark before swapping.
+format_push_string       = "allow"
+# Builder-style `with_*` methods return `Self`; the existing `#[must_use]`
+# discipline lives on aggregate constructors, not every chainable setter.
+return_self_not_must_use = "allow"
+# Match arms grouped by side-effect over body equality (e.g. snake_case wire
+# label tables) — fanning them out keeps adding a new variant trivial.
+match_same_arms          = "allow"
+# Remaining style-only warnings: trailing `continue` is sometimes clearer than
+# rewriting, `_x` underscored bindings document intent at the use site, and
+# `!(a == b)` reads better than `a != b` when paired with a complementary check.
+needless_continue        = "allow"
+used_underscore_binding  = "allow"
+nonminimal_bool          = "allow"
+# Other one-off cosmetic items: large literal formatting, doc link quoting,
+# `Clone::clone_from` swap, `str::replace` chaining, `Iterator::any` ergonomics.
+unreadable_literal           = "allow"
+many_single_char_names       = "allow"
+doc_link_with_quotes         = "allow"
+assigning_clones             = "allow"
+collapsible_str_replace      = "allow"
+trivial_regex                = "allow"
+elidable_lifetime_names      = "allow"
+range_plus_one               = "allow"
+explicit_iter_loop           = "allow"
+implicit_hasher              = "allow"
+ref_option                   = "allow"
 
 [workspace.dependencies]
 anyhow       = "1"
@@ -99,6 +188,22 @@ tree-sitter-go         = "0.25.0"
 # JVM family grammars for code ingest (kebab-parse-code, p10-1C-JK).
 tree-sitter-java       = "0.23.5"
 tree-sitter-kotlin-ng  = "1.1.0"   # bare tree-sitter-kotlin requires ts <0.23; -ng uses tree-sitter-language 0.1 (ts 0.26 compat)
+# C/C++ family grammars for code ingest (kebab-parse-code, p10-1D).
+tree-sitter-c         = "0.24.2"
+tree-sitter-cpp       = "0.23.4"
+# fb-41 PR-9 (kebab-nli): mDeBERTa-v3 XNLI verifier deps. Versions match
+# the fastembed 4.9 transitive set so the ONNX Runtime + tokenizer stack
+# stays single-versioned across the workspace. ort `default-features=false`
+# drops the bundled binary downloader (fastembed already provides one);
+# tokenizers `default-features=false, onig` swaps the default `esaxx` regex
+# backend for `onig` so the build doesn't need libstdc++ headers (verified
+# via PR-9a pre-flight: SentencePiece tokenizer.json loads + KR/EN encode).
+# hf-hub uses `ureq + rustls-tls` to stay aligned with kebab-embed-local's
+# pure-Rust TLS stack.
+ort          = { version = "=2.0.0-rc.9", default-features = false, features = ["ndarray"] }
+tokenizers   = { version = "0.21", default-features = false, features = ["onig"] }
+hf-hub       = { version = "0.4", default-features = false, features = ["ureq", "rustls-tls"] }
+ndarray      = "0.16"
 
 # Disk-footprint trim for dev / test builds. Codegen, opt-level, and
 # behavior are unchanged — only DWARF debug info is reduced (line

HANDOFF.md

@@ -4,7 +4,7 @@
 
 ## 한 줄 요약
 
-P0–P5 + P6 + P7 + P9-1/2/3/4 (Library / Search / Ask / Inspect) 머지 완료. `kebab ingest` 가 markdown / image / PDF / 소스코드 (Rust / Python / TS / JS / Go / Java / Kotlin) / Tier 2 리소스 파일 (yaml/k8s / dockerfile / toml / json / xml / groovy / go-mod) 처리. `kebab search` / `kebab ask` 가 매체 가로질러 결과 + page / code citation 반환. `kebab tui` 가 4 패널 (Library + Search + Ask + Inspect) 제공. P10-2 (Tier 2 resource-aware) 완료 — 다음 후보 = P10-1D (C/C++) 또는 P10-3 (Tier 3 fallback) 또는 P9-5 (desktop tauri) 또는 보류 중인 P8 (audio).
+P0–P5 + P6 + P7 + P9-1/2/3/4 (Library / Search / Ask / Inspect) + P10 전체 머지 완료 (현재 **v0.18.0**). `kebab ingest` 가 markdown / image / PDF / 소스코드 (Rust / Python / TS / JS / Go / Java / Kotlin / C / C++) / Tier 2 리소스 파일 (yaml/k8s / dockerfile / toml / json / xml / groovy / go-mod) + Tier 3 paragraph fallback (shell / 비-k8s YAML / AST 실패 케이스) 처리. `kebab search` / `kebab ask` 가 매체 가로질러 결과 + page / code citation 반환. `kebab tui` 가 4 패널 (Library + Search + Ask + Inspect) 제공. **v0.17.0 cut (2026-05-24)**: 한국어 trigram FTS5 tokenizer (PR #159) + C typedef alias unit (PR #160) + `code_lang_chunk_breakdown` additive (PR #161). **v0.17.1 cut (2026-05-25)**: 확장 도그푸딩 후 `[models.llm] request_timeout_secs` config 노브 (PR #162) + sudo 없이 ollama 설치 + `kebab ask --stream` UX 권장 docs (PR #163). **v0.17.2 cut (2026-05-25)**: v0.17.1 post-dogfood polish — `[image.ocr] request_timeout_secs` 별 노브 (PR #164, v0.17.1 미진행 closure) + `heading_path` FTS5 column filter 로 text-only 매칭 + raw-mode escape hatch (PR #165, 2026-05-24 v0.17.0 trigram entry 의 JSON 노이즈 closure). **v0.18.0 cut (2026-05-26)**: fb-41 multi-hop RAG + NLI verification ship (PR #176-180) — `kebab ask --multi-hop` 의 decompose → decide → synthesize loop + mDeBERTa-v3 XNLI ONNX post-synthesize entailment 검사. dogfood S7 caffeine hallucination 의 silent LLM-self-judge ceiling 해결 (nli_score 0.0035 graceful refuse). 추가 `chore: workspace-wide cleanup + post-PR9 refactor` (PR #181) — clippy::pedantic baseline + H1 config wiring + 9 new tests. 자세한 영향은 [v0.17.0 release notes](https://gitea.altair823.xyz/altair823-org/kebab/releases/tag/v0.17.0) + [v0.17.1 release notes](https://gitea.altair823.xyz/altair823-org/kebab/releases/tag/v0.17.1) + [v0.17.2 release notes](https://gitea.altair823.xyz/altair823-org/kebab/releases/tag/v0.17.2) + [v0.18.0 release notes](https://gitea.altair823.xyz/altair823-org/kebab/releases/tag/v0.18.0). 구조적으로 남은 component 는 P9-5 (desktop tauri) 하나뿐, P8 (audio) 는 사용자 보류.
 
 ## Phase 로드맵
 
@@ -20,18 +20,25 @@ P0–P5 + P6 + P7 + P9-1/2/3/4 (Library / Search / Ask / Inspect) 머지 완료.
 | **P7** | PDF text + page citation | `kebab-parse-pdf` | P5 | ✅ 완료 (3/3 component, page-level chunker + ingest wiring) |
 | **P8** | 음성 transcription + timestamp citation | `kebab-parse-audio` | P5 | ⏸ 보류 (whisper-rs 시스템 dep brainstorm 필요) |
 | **P9** | TUI + desktop app | `kebab-tui`, `kebab-desktop` | P5 | 🟡 진행 (4/5 component — P9-1/2/3/4 완료 [Library / Search / Ask / Inspect], P9-5 desktop 예정 · 도그푸딩 피드백 **20/20 ✅**) |
-| **P10** | code ingest framework | `kebab-parse-code` | P5 | 🟡 진행 중 — 1A-1 ✅ (wire schema + parse-code skeleton + filter flags), 1A-2 ✅ (Rust AST chunker, `code-rust-ast-v1` — v0.7.0), 1B ✅ (Python/TS/JS AST chunkers — v0.8.0 이후), **1C-Go ✅ (Go AST chunker, `code-go-ast-v1` — v0.12.0)**, **1C-JavaKotlin ✅ (Java + Kotlin AST chunkers, `code-java-ast-v1` / `code-kotlin-ast-v1` — v0.13.0)**, **2 ✅ (Tier 2 resource-aware: yaml/k8s + dockerfile + manifest, `k8s-manifest-resource-v1` / `dockerfile-file-v1` / `manifest-file-v1` — v0.14.0)** |
+| **P10** | code ingest framework | `kebab-parse-code` | P5 | 🟡 진행 중 — 1A-1 ✅ (wire schema + parse-code skeleton + filter flags), 1A-2 ✅ (Rust AST chunker, `code-rust-ast-v1` — v0.7.0), 1B ✅ (Python/TS/JS AST chunkers — v0.8.0 이후), **1C-Go ✅ (Go AST chunker, `code-go-ast-v1` — v0.12.0)**, **1C-JavaKotlin ✅ (Java + Kotlin AST chunkers, `code-java-ast-v1` / `code-kotlin-ast-v1` — v0.13.0)**, **2 ✅ (Tier 2 resource-aware: yaml/k8s + dockerfile + manifest, `k8s-manifest-resource-v1` / `dockerfile-file-v1` / `manifest-file-v1` — v0.14.0)**, **3 ✅ (Tier 3 paragraph fallback: code-text-paragraph-v1 — v0.15.0)**, **1D ✅ (C + C++ AST chunkers, code-c-ast-v1 + code-cpp-ast-v1 — v0.16.0)** |
 
 P0~P5 직렬. P6~P9 P5 이후 병렬 가능.
 
 ## Component 카운트
 
-총 33 component task — spec 시점 31 개 + 후속 wiring task 3 (P3-5 / P6-4 / P7-3) 가 머지 시점에 추가됨. per-component 진행 + status 는 [tasks/INDEX.md](tasks/INDEX.md).
+총 33 component task — spec 시점 31 개 + 후속 wiring task 3 (P3-5 / P6-4 / P7-3) 가 머지 시점에 추가됨. v0.18.0 cut 시점에 fb-41 multi-hop RAG + NLI verification (PR-9 5 sub-PRs) 가 P9 추가 component 로 ship — `kebab-nli` 신규 crate (mDeBERTa-v3 XNLI ONNX verifier) + `kebab-rag::ask_multi_hop` (decompose/decide/synthesize loop + step 8.5 NLI hook). per-component 진행 + status 는 [tasks/INDEX.md](tasks/INDEX.md).
 
 ## 머지 후 발견된 버그 / 결정 (요약)
 
 머지 후 발견된 모든 deviation / hotfix 의 dated 로그는 [tasks/HOTFIXES.md](tasks/HOTFIXES.md). 본 요약은 \"누군가가 인수받을 때 알아두면 시간을 많이 절약하는\" 항목만:
 
+- **2026-05-26 v0.18.0 fb-41 multi-hop RAG + NLI verification ship (PR #176-180) + post-PR9 cleanup (PR #181)** — pre-v0.18.0 dogfood (`/build/cache/dogfood-v018/`, 33 assets / 205 chunks, gemma3:4b CPU only / 16 GB RAM) 에서 발견된 S7 caffeine hallucination 의 root cause = LLM-self-judge ceiling (synthesize 가 chunks 와 무관한 Adam optimizer gradient 식을 silent emit, self-judge 가 reject 못함). 학계 표준 (Self-RAG, CRAG, Auto-GDA, MedTrust-RAG) 결론 = deterministic post-synthesis verification. mDeBERTa-v3 XNLI ONNX (280 MB, Xenova HF) 가 `(packed_chunks, answer)` entailment 검사 — `[rag] nli_threshold > 0` (default 0.0 = disabled, production 권장 0.5) 일 때 활성. dogfood retest 측정 — S7 PR-8 baseline `grounded=true + Adam hallucination` → PR-9 `nli_verification_failed, nli_score 0.0035`. wire additive minor — `answer.v1.verification` field + `refusal_reason` 의 `nli_verification_failed` / `nli_model_unavailable` 추가, pre-v0.18 reader 무영향. 5 sub-PR 시퀀스 + cleanup PR (clippy::pedantic baseline + 의도적 30+ allow + H1 `[models.nli].model` config wiring + 9 new tests). post-refactor retest = PR-9d byte-identical (deterministic 확인). 자세한 내용: `tasks/HOTFIXES.md` (2026-05-25 fb-41 PR-9 closure entry + S3 follow-up).
+- **2026-05-25 v0.17.2 post-v0.17.1 polish (PR #164 + #165)** — v0.17.1 의 두 follow-up closure. (1) `[image.ocr] request_timeout_secs` 별 노브 — `crates/kebab-parse-image/src/ocr.rs::REQUEST_TIMEOUT` hard 300s 제거, LLM 쪽 패턴 (PR #162) 을 OCR 어댑터에 동일 적용. 사용자 결정으로 별 노브 분리 (OCR vs LLM 의 cold start 패턴이 달라 독립 조절). v0.17.1 미진행 항목 closure. (2) `chunks_fts` 의 `heading_path` 컬럼이 JSON 표기 + path 세그먼트 까지 trigram 색인 → query false positive 가능 문제 closure. `lexical.rs::build_match_string` 가 non-raw 분기 결과를 `text : (<expr>)` 로 wrap — heading 색인 V007 verbatim 유지, 매칭만 text 한정. 사용자가 명시 heading 검색 하려면 raw mode `'heading_path : <token>'` escape hatch (SKILL.md 갱신). 둘 다 additive (옛 config 호환) / re-ingest 불필요. 자세한 내용: `tasks/HOTFIXES.md` (2026-05-25 v0.17.2 두 entry).
+- **2026-05-25 v0.17.1 post-dogfood (PR #162 + #163)** — 확장 도그푸딩 (16 GB CPU only, gemma4:e4b 시도) 에서 발견된 두 follow-up 한 묶음. (1) `crates/kebab-llm-local/src/ollama.rs::REQUEST_TIMEOUT` hard 300s → `[models.llm] request_timeout_secs` config + env override (additive, default 300, `=0` 은 disable 아닌 "즉시 timeout" 이라 doc 명시). (2) README + SMOKE 에 sudo / systemd 없이 ollama 설치 + ≤4B Q4 권장 모델 + `kebab ask --stream` UX 권장 docs. additive only — 옛 config / wire 호환. 자세한 내용: `tasks/HOTFIXES.md` (2026-05-25).
+- **2026-05-24 v0.17.0 PR-C `code_lang_chunk_breakdown` additive (closure of 2026-05-22 LOW)** — `schema.v1.stats` 에 chunk 수 집계 신규 키. 기존 `code_lang_breakdown` (doc count) 와 sister. 또 기존 두 필드 JSON schema description 의 "chunk count" 오기재 → "doc count" 로 정정. wire additive — schema_version bump 불필요. 자세한 내용: `tasks/HOTFIXES.md` (2026-05-24 PR-C).
+- **2026-05-24 v0.17.0 PR-B C typedef alias unit (closure of 2026-05-21)** — `kebab-parse-code::c::extract_blocks` 의 `type_definition` 분기로 inner anonymous struct/enum/union → declarator 의 typedef alias 이름으로 synthetic unit 방출. `PARSER_VERSION code-c-v1` → `code-c-v2` bump + 같은-asset/다른-doc_id 케이스용 `purge_workspace_path_for_parser_bump` cascade (`stale_chunk_ids_for_workspace_path_except_doc_id` + `purge_document_at_workspace_path_except_doc_id` helper 신규). 사용자 작업 불필요 (다음 ingest 가 자동 재처리). 자세한 내용: `tasks/HOTFIXES.md` (2026-05-24 PR-B).
+- **2026-05-24 v0.17.0 PR-A 한국어 trigram tokenizer 채택 (closure of 2026-05-22 한국어 lexical)** — `chunks_fts` 가 FTS5 `unicode61` → `trigram` 으로 V007 migration (자동 backfill, re-ingest 불필요). `lexical.rs::build_match_string` trigram-aware 재설계 — multi-token 한국어 query (`해시 충돌`) 가 whole-phrase 후보로 hit, 한영 혼합 (`Rust 충돌은`) 도 OR-combined. 2자 이하 query 는 0-hit + CLI/TUI/wire `hint` 안내. 영어 lexical 도 substring 매칭으로 바뀜 (recall ↑ / 단어 경계 ↓). `kebab.sqlite` 크기 ~2-5배 증가 (trigram index). 자세한 내용: `tasks/HOTFIXES.md` (2026-05-24).
+- **2026-05-22 P10 종합 도그푸딩 round 2 (한국어 lexical 검색 한계)** — `kebab search --mode lexical` 의 한국어 query 가 FTS5 `unicode61` 토크나이저에서 거의 0 hit (어절 단위 토큰화 → 부분 매칭 불가). 기본 hybrid 모드는 `multilingual-e5-small` vector 가 carry 해 한국어 검색 정상. **closure**: 위 2026-05-24 v0.17.0 entry.
 - **2026-05-20 P10-1B (Rust 1A symbol path 비일관 + expression-level 함수 미방출)** — (a) Rust `code-rust-ast-v1` 은 file-scope nesting 만 (workspace path prefix 없음), 1B 의 Python/TypeScript/JavaScript 는 workspace 경로 → module path prefix 사용 (비일관 수용, retrofit = chunker_version bump + reindex 필요, 사용자 명시 요청까지 보류); (b) TS/JS 의 `const foo = () => {...}` 같은 expression-level 함수는 `<top-level>` glue 로 처리됨 (declaration-level 단위만 1B 1차 범위). 자세한 내용: `tasks/HOTFIXES.md` (2026-05-20) 두 항목.
 - **2026-05-19 P10-1A-2 (code_rust_ast_v1.rs + SourceType)** — `AST_CHUNK_MAX_LINES` 상수가 `IngestCodeCfg.ast_chunk_max_lines` 를 읽지 않고 모듈 상수 200 고정 (Chunker trait 이 per-medium config 미노출); `SourceType::Code` variant 부재로 code 파일이 `SourceType::Note` 로 분류됨 — 두 항목 모두 `tasks/HOTFIXES.md` (2026-05-19) 에 기록.
 - **2026-05-07 fb-26 (progress.rs)** — `Aborted` unconditional writeln (TTY duplicate) + `Completed` TTY no summary fixed; `KEBAB_PROGRESS=plain` env + quiet suppression added
@@ -81,13 +88,13 @@ P0~P5 직렬. P6~P9 P5 이후 병렬 가능.
 
 ## 다음 task 후보
 
-- **P9-2 TUI search** — `App.search` slot 채움. Library 의 `/` 가 enable 됨.
-- **P9-3 TUI ask** — `App.ask` slot 채움. `?` enable.
-- **P9-4 TUI inspect** — `App.inspect` slot 채움. `Enter` enable.
-- **P9-5 desktop tauri** — 별도 분기. PDF citation rendering UI 가치 큼.
-- **P8 audio brainstorm** — whisper-rs 시스템 dep 받을지 / 외부 transcription endpoint 사용할지 사용자 결정 필요. 사용자 패턴 (책+PDF 위주, audio 의향 없음) 상 후순위.
+구조적으로 미완인 component 는 P9-5 하나뿐. 나머지는 도그푸딩 follow-up (아래 "P10 dogfooding 백로그") 또는 사용자 결정 대기.
 
-P9-2/3/4 는 P9-1 의 parallel-safety contract (sub-state slot 패턴) 덕에 병렬 진행 가능 — 같은 `App` 손대지 않음.
+- **P9-5 desktop tauri** — 마지막 남은 P9 component. `kebab-desktop` crate + Tauri 앱, 별도 분기. PDF citation rendering UI 가치 큼. 사용자 우선순위 (P9 우선 · 책/PDF 위주) 와 부합.
+- **P10 도그푸딩 round 2 follow-up** — ✅ v0.17.0 cut (2026-05-24) 으로 세 항목 모두 closure (한국어 trigram PR-A + C typedef alias PR-B + code_lang_chunk_breakdown additive PR-C). 상세 cross-link: 아래 "P10 dogfooding 백로그" 절 + `tasks/HOTFIXES.md` (2026-05-24 PR-A/B/C).
+- **P8 audio brainstorm** — whisper-rs 시스템 dep 받을지 / 외부 transcription endpoint 사용할지 사용자 결정 필요. 사용자 패턴 (책+PDF 위주, audio 의향 없음) 상 보류.
+- **fb-41 multi-hop reasoning** — ⏳ 미구현, XL, eval 인프라 선행 + brainstorm 필요.
+- **Rust symbol path retrofit** — Rust `code-rust-ast-v1` symbol 이 file-scope-only (1B+ 는 module prefix). `code-rust-ast-v2` bump + Rust corpus re-ingest 비용 → 사용자 명시 요청까지 보류. HOTFIXES `2026-05-20`.
 
 ### P9 dogfooding 백로그 (fb-26 ~ fb-42) — release 분할
 
@@ -96,11 +103,20 @@ P9-2/3/4 는 P9-1 의 parallel-safety contract (sub-state slot 패턴) 덕에
 - **0.3.0 — agent foundation** ✅ cut 2026-05-07: fb-26 (log), fb-27 (introspection/error wire), fb-28 (readonly/quiet). ~~fb-29 (daemon)~~ → 🚫 **deferred** — fb-30 stdio MCP 가 동일 가치를 daemon 복잡도 없이 제공.
 - **0.4.0 — agent integration (MCP)** ✅ cut: fb-30 (MCP stdio), fb-31 (single-file/stdin ingest).
 - **0.5.0 — agent surface refinement (additive)** ✅ cut 2026-05-10: fb-32 (stale doc indicator), fb-33 (streaming ask), fb-34 (output budget controls), fb-35 (verbatim fetch), fb-36 (search filter args), fb-37 (trace + stats). 모두 wire schema additive minor.
-- **0.6.0 — RAG quality** 🟡 진행: fb-38 (score semantics) ✅ 머지 (2026-05-10), fb-40 (fact-grounded answer / rag-v2 prompt) ✅ 머지 (2026-05-10), fb-39 (retrieval precision tuning, embedding_version cascade) — 미진행 (eval golden set 선행 필요).
-- **0.7.0 또는 P+**: fb-41 (multi-hop reasoning, XL), fb-42 (bulk multi-query / rerank, Nice).
+- **0.6.0 — RAG quality** ✅ 대부분 머지 (2026-05-10): fb-38 (score semantics) ✅, fb-39 (eval foundation — `precision_at_k_chunk` metric) ✅, fb-39b (embedding upgrade — multilingual-e5-large default) ✅, fb-40 (fact-grounded answer / rag-v2 prompt) ✅. 잔여 = fb-39 의 retrieval precision lever 실제 적용 (eval golden set 확장 선행 필요).
+- **0.7.0 또는 P+**: fb-41 (multi-hop reasoning, XL) — ⏳ 미구현 · brainstorm 필요; fb-42 (bulk multi-query) ✅ 머지 (2026-05-10, bulk only — rerank hint 은 deferred).
 
 각 fb spec frontmatter 의 `target_version` 필드가 source of truth. INDEX.md 의 release subheader 도 동일 grouping.
 
+### P10 dogfooding 백로그 (2026-05-22 round 2)
+
+P10 종합 도그푸딩 round 2 (`/build/cache/dogfood-p10b/`, OSS 8 repo + 한국어 위키 문서 10편) 에서 발견된 follow-up 후보. 자세한 내용 + 우선순위 근거는 `tasks/HOTFIXES.md` (2026-05-22).
+
+- **한국어 lexical tokenizer** — ✅ v0.17.0 (2026-05-24) PR-A 머지 (#159). V007 trigram migration 자동 backfill + `build_match_string` 재설계 + CLI/TUI/wire hint. HOTFIXES `2026-05-24 PR-A` 참조.
+- **code_lang_chunk_breakdown chunk 단위 집계 (LOW)** — ✅ v0.17.0 (2026-05-24) PR-C 머지 (#161). `schema.v1.stats` additive 필드. HOTFIXES `2026-05-24 PR-C` 참조.
+- **C typedef-wrapped struct (LOW)** — ✅ v0.17.0 (2026-05-24) PR-B 머지 (#160). `type_definition` 분기 + `PARSER_VERSION code-c-v2` bump + orphan purge cascade. HOTFIXES `2026-05-24 PR-B` 참조.
+- **ranking glue chunk 편향 (deferred)** — 자동 heuristic 은 user intent misalignment 위험. 사용자 명시 요청 전까지 surface 변경 0 유지. 1주+ 실사용 후 재 brainstorm.
+
 ## 검증된 운영 동작 (release binary, fastembed enabled)
 
 P7-3 머지 직후 25 시나리오 smoke 통과 — markdown + image + PDF 5 자산 워크스페이스에서 doctor / ingest / list / inspect / search (lex/vec/hybrid) / re-ingest / byte-edit re-ingest / corrupt PDF / RAG ask + page citation 모두. 자세한 시나리오 표는 conversation 기록 참조; 워크스페이스에 직접 돌려보는 절차는 [docs/SMOKE.md](docs/SMOKE.md).

README.md

@@ -6,6 +6,20 @@
 
 - **Rust toolchain** ≥ 1.85 (workspace 가 edition 2024 + resolver 3 사용). [rustup](https://rustup.rs) 권장.
 - **Ollama** — `kebab ask` 와 이미지 OCR/caption 가 사용. `https://ollama.com/download` 에서 설치 후 `ollama serve` 실행. 기본 LLM 은 gemma4 계열 (`ollama pull gemma4:e4b`) — OCR / caption 도 같은 family 라 모델 하나만 pull 하면 됨. 더 큰 variant 원하면 `gemma4:26b` 등으로 config override. config 의 `[models.llm].endpoint` 에 host:port 명시.
+  - **CPU only / RAM ≤ 16 GB 환경 권장 모델**: gemma4:e4b (8B) 는 CPU 추론에 무거워 RAG 한 답변이 5분을 넘기기 쉽다 — `[models.llm] request_timeout_secs` 의 기본 300 s 한도에 걸려 `error: kb-rag: llm.generate_stream` 으로 떨어진다 (HOTFIXES 2026-05-25). `gemma3:4b` / `qwen2.5:3b` / `phi3:mini` 같은 ≤ 4B Q4 모델로 바꾸면 답변 1-3 분에 안정 동작 (확장 도그푸딩에서 검증). 모델 storage 가 부담이면 `OLLAMA_MODELS=/path` env 로 위치 분리 가능.
+  - **`request_timeout_secs` 노브 (v0.17.0)**: `[models.llm] request_timeout_secs = 1200` (또는 `KEBAB_MODELS_LLM_REQUEST_TIMEOUT_SECS=1200`) 로 한도를 늘려 큰 모델도 시도 가능. 단 응답 동안 RAM 점유가 길어진다. **`= 0` 은 disable 이 아니라 "즉시 timeout"** (reqwest 의 의미상) — "사실상 무제한" 의도면 `u64::MAX` 또는 `86400` 같이 큰 finite 값 사용.
+  - **sudo 없이 설치 (격리 디렉토리 사용)**: `install.sh` 가 `/usr/local/bin/ollama` + `systemd` 유닛까지 건드리는 게 부담이면 binary tarball 만 받아 사용자 디렉토리에 풀고 env 로 모델 위치 분리하면 된다.
+    ```bash
+    mkdir -p /opt/ollama/{models,logs}
+    curl -fL https://ollama.com/download/ollama-linux-amd64.tar.zst -o /tmp/ollama.tar.zst
+    zstd -d /tmp/ollama.tar.zst -o /tmp/ollama.tar && tar -xf /tmp/ollama.tar -C /opt/ollama/
+    # bin/ollama + lib/ollama/ 가 풀린다. 모델 디렉토리는 OLLAMA_MODELS 로 분리.
+    OLLAMA_MODELS=/opt/ollama/models OLLAMA_HOST=127.0.0.1:11434 \
+        /opt/ollama/bin/ollama serve > /opt/ollama/logs/serve.log 2>&1 &
+    /opt/ollama/bin/ollama pull gemma3:4b
+    ```
+    루트 디스크 부담을 분리하고 싶을 때 (`~/.ollama/models` 가 기본) 그대로 활용. systemd 가 없는 컨테이너 / WSL2 / 회사 머신 등에서 유용.
+  - **`kebab ask --stream` 권장 (fb-33)**: 모델 cold start 가 길 때 (8B+ 또는 첫 호출) `--stream` 으로 토큰을 stderr 에 ndjson 으로 흘려 받으면 5 분 timeout 한도 안에서도 첫 토큰이 빨리 보여 사용자 체감이 개선된다. 동일 inference 시간이라도 wait-and-pray 보다 progressive 가 안정적. CLI: `kebab ask "..." --stream 2> events.ndjson > final.json`. MCP host 도 `streaming_ask` capability flag 가 `true` 면 자동 사용 권장.
 - **빌드 디스크** — 첫 빌드 시 `target/` 가 6–10 GB (Lance + DataFusion + fastembed). 여유 확인.
 - **fastembed 모델** — 첫 `kebab ingest` 시 `multilingual-e5-large` (~1.3 GB, fb-39b) 자동 다운로드. `config.toml` 에서 `model = "multilingual-e5-small"` 로 명시하면 이전 모델 사용.
 
@@ -70,12 +84,12 @@ kebab doctor
 | 명령 | 동작 |
 |------|------|
 | `kebab init` | XDG 경로에 데이터 디렉토리 + config.toml 생성 |
-| `kebab ingest [<path>]` | Markdown / 이미지 / PDF / Rust 소스코드 색인 (idempotent). TTY 에서는 stderr 진행 바, non-TTY (CI / pipe) 는 stderr 한 줄씩, `--json` 은 stdout 에 `ingest_progress.v1` 라인 streaming 후 마지막에 `ingest_report.v1`. Ctrl-C 한 번이면 현재 asset 마무리 후 abort (부분 commit 보존, idempotent re-run), 두 번째 Ctrl-C 는 hard exit. Markdown title 이 frontmatter 에 없어도 첫 H1 → H2 → 첫 paragraph 80 자 → 파일명 순으로 자동 채움 (parser_version `md-frontmatter-v2`) — 기존 색인된 doc 도 다음 ingest 에서 새 title 로 갱신. **Incremental** (p9-fb-23): 두 번째 이후의 ingest 는 변하지 않은 doc (blake3 + parser/chunker/embedder version 모두 동일) 의 parse/chunk/embed/vector upsert 를 자동 스킵. final summary 에 `N unchanged` 카운트 표시. `--force-reingest` 로 skip 무시 강제 재처리. **지원 형식** (extractor 자동 결정 — config 에 명시 불가): Markdown (`.md`), 이미지 (`.png` / `.jpg` / `.jpeg`, OCR + caption), PDF (`.pdf`), **소스코드** (`.rs` → `code-rust-ast-v1`, `.py` → `code-python-ast-v1`, `.ts`/`.tsx` → `code-ts-ast-v1`, `.js`/`.mjs`/`.cjs`/`.jsx` → `code-js-ast-v1`, `.go` → `code-go-ast-v1`, `.java` → `code-java-ast-v1`, `.kt`/`.kts` → `code-kotlin-ast-v1` — 모두 tree-sitter AST chunker; **Tier 2 리소스 파일**: `.yaml`/`.yml` → `k8s-manifest-resource-v1` (apiVersion+kind 파싱), `Dockerfile`/`Dockerfile.*`/`*.dockerfile` → `dockerfile-file-v1` (전체 파일), `Cargo.toml`/`pyproject.toml`/`.toml`/`package.json`/`tsconfig.json`/`.json`/`pom.xml`/`.xml`/`build.gradle`/`.gradle`/`go.mod` → `manifest-file-v1` (전체 파일) — yaml (k8s) / dockerfile / toml / json / xml / groovy / go-mod 지원). 다른 확장자는 자동 skip — `IngestItem.warnings` 에 사유 (`"unsupported media type: .docx"` 등), `IngestReport.skipped_by_extension` 에 카운트 분류, CLI / TUI summary 에 breakdown 표시. 코드 chunk 는 `citation.kind = "code"` 에 `citation.lang = "<lang>"` + `symbol` + line range 를 담고, SearchHit top-level 에 `code_lang` + `repo` (`.git/` walk-up 의 디렉토리 이름) 가 backfill 됨. `--code-lang rust` / `--code-lang python` / `--code-lang typescript` / `--code-lang javascript` / `--code-lang go` / `--code-lang java` / `--code-lang kotlin` / `--code-lang yaml` / `--code-lang dockerfile` / `--code-lang toml` / `--code-lang json` / `--code-lang xml` / `--code-lang groovy` / `--code-lang go-mod` / `--media code` filter 로 언어별·코드 전용 검색 가능 (p10-1A-1 filter flags). Python symbol 은 workspace 경로 → dotted module path prefix (예: `kebab_eval.metrics.compute_mrr`), TS/JS symbol 은 slash-style module path prefix (예: `src/Foo.Foo.search`), Go symbol 은 `package.Func` / `package.(*Receiver).Method` 형식, Java / Kotlin symbol 은 `com.foo.Foo.bar` 형식 (패키지 + 클래스 + 메서드/필드). |
-| `kebab search --mode {lexical,vector,hybrid} "<query>" [--no-cache] [--max-tokens N] [--snippet-chars N] [--cursor <opaque>] [--tag T] [--lang L] [--path-glob G] [--trust-min LEVEL] [--media TYPE] [--ingested-after RFC3339] [--doc-id ID] [--trace] [--bulk] [--repo NAME ...] [--code-lang LIST]` | 검색. hybrid는 RRF fusion, citation 포함. 같은 process 안에서 동일 query (NFKC + trim + lowercase 정규화) 반복 시 in-process LRU 캐시 hit (capacity = `[search] cache_capacity`, default 256). `--no-cache` 로 강제 bypass — 디버깅용. ingest commit 발생 시 `kv['corpus_revision']` bump 으로 모든 entry 자동 stale. **`--max-tokens` / `--snippet-chars` / `--cursor` (p9-fb-34)** — agent budget controls. `--json` 출력은 `search_response.v1` wrapper (`{hits, next_cursor, truncated}`) — pre-fb-34 의 bare array 와 호환 안 됨. mismatched cursor → `error.v1.code = stale_cursor`. **filter flags (p9-fb-36):** `--tag` 는 반복 가능 flag (`--tag rust --tag async`) 로 OR 매칭, `--media` 는 `,` 구분 다중 값 OR 매칭, 나머지 flags 간은 AND 조합. `--trust-min` 은 `primary\|secondary\|generated` 중 하나 (해당 level 이상 포함). `--ingested-after` 는 RFC3339 UTC — 파싱 실패 시 `error.v1.code = config_invalid` (exit 2). `--media md` 는 `markdown` alias 로 정규화. 알 수 없는 `--media` 값은 무조건 empty hits (오류 아님). **`--trace` (p9-fb-37)** — `search_response.v1.trace` 에 lexical / vector pre-fusion 후보 + RRF union + per-stage timing (`lexical_ms` / `vector_ms` / `fusion_ms` / `total_ms`) 노출. trace 요청은 캐시 우회 (`--no-cache` 없이도 항상 cold). **`--bulk` (p9-fb-42)** — stdin ndjson 으로 N query 한 번에 실행. `--json` 면 stdout per-query ndjson (`bulk_search_item.v1`) + stderr summary (`bulk_summary: total=N succeeded=S failed=F`). Cap 100. agent 가 query decomposition 후 sub-query 일괄 실행 시 single round-trip — App instance 재사용으로 캐시 / embedder cold-start 비용 한 번만. Per-query failure 는 item 의 `error` (error.v1) 에 격리, 다른 query 계속 진행. **code corpus filters (p10-1A-1):** `--repo` 는 반복 가능 (`--repo kebab --repo other`) OR 매칭. `--code-lang` 는 반복 또는 comma 다중 값 (`--code-lang rust,python`), 알 수 없는 값은 빈 hits. `--media code` 는 Tier 1/2/3 모든 code chunk 포함. 1A-1 시점에서는 indexed 된 code chunk 가 없어 filter 가 항상 빈 결과 — 1A-2 (Rust AST chunker) 머지 이후 실효. |
+| `kebab ingest [<path>]` | Markdown / 이미지 / PDF / Rust 소스코드 색인 (idempotent). TTY 에서는 stderr 진행 바, non-TTY (CI / pipe) 는 stderr 한 줄씩, `--json` 은 stdout 에 `ingest_progress.v1` 라인 streaming 후 마지막에 `ingest_report.v1`. Ctrl-C 한 번이면 현재 asset 마무리 후 abort (부분 commit 보존, idempotent re-run), 두 번째 Ctrl-C 는 hard exit. Markdown title 이 frontmatter 에 없어도 첫 H1 → H2 → 첫 paragraph 80 자 → 파일명 순으로 자동 채움 (parser_version `md-frontmatter-v2`) — 기존 색인된 doc 도 다음 ingest 에서 새 title 로 갱신. **Incremental** (p9-fb-23): 두 번째 이후의 ingest 는 변하지 않은 doc (blake3 + parser/chunker/embedder version 모두 동일) 의 parse/chunk/embed/vector upsert 를 자동 스킵. final summary 에 `N unchanged` 카운트 표시. `--force-reingest` 로 skip 무시 강제 재처리. **지원 형식** (extractor 자동 결정 — config 에 명시 불가): Markdown (`.md`), 이미지 (`.png` / `.jpg` / `.jpeg`, OCR + caption), PDF (`.pdf`), **소스코드** (`.rs` → `code-rust-ast-v1`, `.py` → `code-python-ast-v1`, `.ts`/`.tsx` → `code-ts-ast-v1`, `.js`/`.mjs`/`.cjs`/`.jsx` → `code-js-ast-v1`, `.go` → `code-go-ast-v1`, `.java` → `code-java-ast-v1`, `.kt`/`.kts` → `code-kotlin-ast-v1`, `.c`/`.h` → `code-c-ast-v1`, `.cpp`/`.cc`/`.cxx`/`.hpp`/`.hh`/`.hxx` → `code-cpp-ast-v1` — 모두 tree-sitter AST chunker; **Tier 2 리소스 파일**: `.yaml`/`.yml` → `k8s-manifest-resource-v1` (apiVersion+kind 파싱), `Dockerfile`/`Dockerfile.*`/`*.dockerfile` → `dockerfile-file-v1` (전체 파일), `Cargo.toml`/`pyproject.toml`/`.toml`/`package.json`/`tsconfig.json`/`.json`/`pom.xml`/`.xml`/`build.gradle`/`.gradle`/`go.mod` → `manifest-file-v1` (전체 파일) — yaml (k8s) / dockerfile / toml / json / xml / groovy / go-mod 지원); **Tier 3 paragraph fallback** (`.sh`/`.bash`/`.zsh` → `code-text-paragraph-v1`, blank-line paragraph split + 80-line/20-overlap line-window. Tier 1/2 가 0 chunk 또는 Err 시 자동 fallback — 비-k8s YAML 같은 케이스 picked up. symbol = None, lang 은 원본 보존.). 다른 확장자는 자동 skip — `IngestItem.warnings` 에 사유 (`"unsupported media type: .docx"` 등), `IngestReport.skipped_by_extension` 에 카운트 분류, CLI / TUI summary 에 breakdown 표시. 코드 chunk 는 `citation.kind = "code"` 에 `citation.lang = "<lang>"` + `symbol` + line range 를 담고, SearchHit top-level 에 `code_lang` + `repo` (`.git/` walk-up 의 디렉토리 이름) 가 backfill 됨. `--code-lang rust` / `--code-lang python` / `--code-lang typescript` / `--code-lang javascript` / `--code-lang go` / `--code-lang java` / `--code-lang kotlin` / `--code-lang yaml` / `--code-lang dockerfile` / `--code-lang toml` / `--code-lang json` / `--code-lang xml` / `--code-lang groovy` / `--code-lang go-mod` / `--code-lang shell` / `--code-lang c` / `--code-lang cpp` / `--media code` filter 로 언어별·코드 전용 검색 가능 (p10-1A-1 filter flags). Python symbol 은 workspace 경로 → dotted module path prefix (예: `kebab_eval.metrics.compute_mrr`), TS/JS symbol 은 slash-style module path prefix (예: `src/Foo.Foo.search`), Go symbol 은 `package.Func` / `package.(*Receiver).Method` 형식, Java / Kotlin symbol 은 `com.foo.Foo.bar` 형식 (패키지 + 클래스 + 메서드/필드). |
+| `kebab search --mode {lexical,vector,hybrid} "<query>" [--no-cache] [--max-tokens N] [--snippet-chars N] [--cursor <opaque>] [--tag T] [--lang L] [--path-glob G] [--trust-min LEVEL] [--media TYPE] [--ingested-after RFC3339] [--doc-id ID] [--trace] [--bulk] [--repo NAME ...] [--code-lang LIST]` | 검색. hybrid는 RRF fusion, citation 포함. 같은 process 안에서 동일 query (NFKC + trim + lowercase 정규화) 반복 시 in-process LRU 캐시 hit (capacity = `[search] cache_capacity`, default 256). `--no-cache` 로 강제 bypass — 디버깅용. ingest commit 발생 시 `kv['corpus_revision']` bump 으로 모든 entry 자동 stale. **`--max-tokens` / `--snippet-chars` / `--cursor` (p9-fb-34)** — agent budget controls. `--json` 출력은 `search_response.v1` wrapper (`{hits, next_cursor, truncated}`) — pre-fb-34 의 bare array 와 호환 안 됨. mismatched cursor → `error.v1.code = stale_cursor`. **filter flags (p9-fb-36):** `--tag` 는 반복 가능 flag (`--tag rust --tag async`) 로 OR 매칭, `--media` 는 `,` 구분 다중 값 OR 매칭, 나머지 flags 간은 AND 조합. `--trust-min` 은 `primary\|secondary\|generated` 중 하나 (해당 level 이상 포함). `--ingested-after` 는 RFC3339 UTC — 파싱 실패 시 `error.v1.code = config_invalid` (exit 2). `--media md` 는 `markdown` alias 로 정규화. 알 수 없는 `--media` 값은 무조건 empty hits (오류 아님). **`--trace` (p9-fb-37)** — `search_response.v1.trace` 에 lexical / vector pre-fusion 후보 + RRF union + per-stage timing (`lexical_ms` / `vector_ms` / `fusion_ms` / `total_ms`) 노출. trace 요청은 캐시 우회 (`--no-cache` 없이도 항상 cold). **`--bulk` (p9-fb-42)** — stdin ndjson 으로 N query 한 번에 실행. `--json` 면 stdout per-query ndjson (`bulk_search_item.v1`) + stderr summary (`bulk_summary: total=N succeeded=S failed=F`). Cap 100. agent 가 query decomposition 후 sub-query 일괄 실행 시 single round-trip — App instance 재사용으로 캐시 / embedder cold-start 비용 한 번만. Per-query failure 는 item 의 `error` (error.v1) 에 격리, 다른 query 계속 진행. **code corpus filters (p10-1A-1):** `--repo` 는 반복 가능 (`--repo kebab --repo other`) OR 매칭. `--code-lang` 는 반복 또는 comma 다중 값 (`--code-lang rust,python`), 알 수 없는 값은 빈 hits. `--media code` 는 Tier 1/2/3 모든 code chunk 포함. 1A-1 시점에서는 indexed 된 code chunk 가 없어 filter 가 항상 빈 결과 — 1A-2 (Rust AST chunker) 머지 이후 실효. **v0.17.0 trigram tokenizer (한국어 + 영어 동작 변경):** `chunks_fts` 가 FTS5 `trigram` 으로 동작 — 한국어 query 는 3자 이상 substring 매칭 (`해시 충돌` 같은 multi-token 도 whole-phrase 후보로 hit), 영어도 substring 매칭 (`token` 이 `tokenizer` 도 hit, recall ↑ / 단어 경계 ↓). 2자 이하 query 는 0-hit + stderr `[hint] 3자 이상 키워드 권장` + `search_response.v1.hint` 필드 (raw FTS5 mode `'...'` 제외). `kebab.sqlite` 파일 크기는 trigram index 비대화로 ~2-5배 또는 수백 MB 증가 (V007 자동 backfill, re-ingest 불필요). |
 | `kebab list docs` | 색인된 문서 목록 |
 | `kebab inspect doc <id>` / `kebab inspect chunk <id>` | raw record 보기 |
 | `kebab fetch chunk <id> [--context N]` / `kebab fetch doc <id> [--max-tokens N]` / `kebab fetch span <doc_id> <ls> <le> [--max-tokens N]` | (p9-fb-35) verbatim text fetch from indexed corpus. wire = `fetch_result.v1` (kind discriminator). chunk: target + ±N ordinal-context chunks. doc: full normalized markdown. span: 1-based line range (PDF/audio rejected as `error.v1.code = span_not_supported`). chars/4 budget on doc/span. |
-| `kebab ask "<query>" [--show-citations / --hide-citations] [--session <id>] [--stream]` | RAG 답변 + 근거 인용. 답변 후 `근거:` block 으로 full path / line range / score 한 줄씩 (default ON — `--hide-citations` 로 끄기, pipe 시 유용). 근거 부족 시 거절. Ollama 필요. `--session <id>` 로 multi-turn — 첫 호출에서 SQLite `chat_sessions` 에 자동 생성, 이후 호출은 prior turns 를 history 로 받아 follow-up. session id 는 사용자 지정 (e.g. `kb-rust-async-2026-05`) — `kebab reset --data-only` 로 모든 session wipe. **`--stream` (p9-fb-33)** 로 ndjson `answer_event.v1` event (retrieval_done → token* → final) 를 stderr 에 흘리고 stdout 마지막 줄에 기존 `answer.v1` — agent 가 token 즉시 소비 가능 |
+| `kebab ask "<query>" [--show-citations / --hide-citations] [--session <id>] [--stream] [--multi-hop]` | RAG 답변 + 근거 인용. 답변 후 `근거:` block 으로 full path / line range / score 한 줄씩 (default ON — `--hide-citations` 로 끄기, pipe 시 유용). 근거 부족 시 거절. Ollama 필요. `--session <id>` 로 multi-turn — 첫 호출에서 SQLite `chat_sessions` 에 자동 생성, 이후 호출은 prior turns 를 history 로 받아 follow-up. session id 는 사용자 지정 (e.g. `kb-rust-async-2026-05`) — `kebab reset --data-only` 로 모든 session wipe. **`--stream` (p9-fb-33)** 로 ndjson `answer_event.v1` event (retrieval_done → token* → final) 를 stderr 에 흘리고 stdout 마지막 줄에 기존 `answer.v1` — agent 가 token 즉시 소비 가능. **`--multi-hop` (v0.18.0 fb-41)** — single-pass 대신 decompose → decide → synthesize 의 N-hop loop. compound 질문 (cross-doc / prereq chain) 에 효과적. 최종 답변 후 mDeBERTa-v3 XNLI 가 `(packed_chunks, generated_answer)` entailment 검사 — `[rag] nli_threshold > 0` (default 0.0 = disabled, production 권장 0.5) 일 때 활성. entailment < threshold → `refusal_reason = "nli_verification_failed"` (LLM-self-judge ceiling 극복, S7 caffeine hallucination 같은 케이스 catch). 첫 호출 시 ~280 MB ONNX model 자동 다운로드 + RAM peak ~7-8 GB (gemma3:4b 기준). model unavailable 시 `refusal_reason = "nli_model_unavailable"`, 우회는 `[rag] nli_threshold = 0` 임시 disable. |
 | `kebab doctor` | 설정/모델/DB 헬스 체크 |
 | `kebab tui` | Ratatui 셸 (Library + Search + Ask + Inspect 패널, desktop 진행 중). Library 에서 `r` 키로 background ingest 시작 — 화면 하단 status bar 가 진행 표시, 완료/abort 시 final 라인 잠시 유지 후 자동 hide. ingest 진행 중 `Esc` / `Ctrl-C` 가 cancel signal (그 외에는 quit). vim-style mode (header 우측 `-- NORMAL --` / `-- INSERT --`) — Library/Inspect 는 자동 NORMAL, Search/Ask 는 자동 INSERT. `i` 로 Normal→Insert (모든 pane — p9-fb-21), `Esc` 로 Insert→Normal 어디서나. mode-authoritative dispatch — Search 의 `j/k/o/g`, Ask 의 `e/j/k` 는 NORMAL 모드에서만 명령으로 동작, INSERT 에서는 입력 문자로 typing. (Search 의 chunk inspect 키는 `i`→`o` 로 rebind — `i` 가 universal Insert toggle.) **`F1` 로 cheatsheet popup** (현재 pane 의 키 매핑 + global 토글 표) — `Esc` / `F1` 로 닫기. Search 패널은 200ms debounce 후 background worker 가 검색 — 키 입력으로 UI freeze 안 됨, 사용자가 계속 타이핑하면 stale 결과 자동 폐기 (generation counter). Ask 패널은 multi-turn — 같은 conversation 안에서 Q1/A1, Q2/A2 transcript 누적, 다음 질문이 이전 턴을 history 로 받아 답변. 답변 본문은 markdown 렌더 (bold/italic/inline code/heading/list/code fence/table/blockquote, raw `**bold**` 가 실제 굵게 표시). `Ctrl-L` 로 새 conversation 시작. Search 의 `g` 키가 `$EDITOR` (기본 `vi`) 로 hit 의 citation 위치 열기 — 종료 후 TUI 화면이 자동으로 깨끗이 redraw. CLI `kebab ask` 는 raw markdown 그대로 (terminal 호환성 위해). Library 의 doc-list 가 한글 / 일본어 / 중국어 (CJK) 제목을 wide-char 정확한 column width 로 truncate — 한글 제목이 한 줄을 넘기지 않음 (CJK 1 자 = 2 col). Search/Ask/Filter 입력의 cursor 가 wide char 위에서 column 단위로 정렬 — 한글 입력 시 caret 이 글자 옆에 정확히 놓임. `← / →` 로 입력 문자열 중간 cursor 이동 (한글 한 글자 = 2 column 이라도 한 번에 이동), `Home / End` 로 양 끝 점프, `Delete` 로 cursor 위치 char 삭제 — 모든 input pane (Ask / Search / Library filter overlay) 동일 (p9-fb-22). Ask 트랜스크립트는 새 답변이 viewport 아래로 누적될 때 자동으로 tail 을 따라감 (auto-scroll); `j` / `k` 로 위로 스크롤하면 freeze, `Shift-G` 로 다시 bottom + auto-tail 재개. 화면 하단 hint line 은 한국어 동사구로 (`"위로"` / `"아래로"` / `"필터"` / `"타이핑 검색어"` / `"Esc 로 NORMAL 모드"` / `"i 입력모드"` 등) + 현재 (pane, mode) 조합에 맞춰 자동 분기, **첫 fragment 가 항상 `F1 도움말`** (cheatsheet 발견성 보장). 모든 모드에서 항상 떠 있는 상태바 — `kebab v<version> │ <pane> │ <docs> docs │ <state>` (state: streaming/searching/indexing/idle, ingest 진행 중에는 progress 가 같은 자리에 흡수됨). Ask 진입 시 conversation id 8 자 prefix 도 함께 표시. Ask 트랜스크립트와 Inspect 양쪽에서 `PgUp / PgDn` 으로 10 줄씩 페이지 스크롤. Library 의 doc list 위에는 `TITLE / TAGS / UPDATED / CHUNKS` 컬럼 헤더 행 표시 (display-width 정렬, Hangul / CJK 안전). |
 | `kebab reset [--all / --data-only / --vector-only / --config-only] [--yes]` | XDG 데이터 wipe. **Irreversible.** TTY 면 confirm prompt, 아니면 `--yes` 필수. `--vector-only` 는 SQLite `embedding_records` 도 함께 truncate (orphan 방지) |
@@ -132,7 +146,7 @@ flowchart TB
 
     subgraph Pipeline["도메인 + 파이프라인"]
         parse["parse-md / parse-pdf / parse-image / parse-code"]
-        chunker["chunker (md-heading-v1, pdf-page-v1, code-rust-ast-v1, code-python-ast-v1, code-ts-ast-v1, code-js-ast-v1, code-go-ast-v1)"]
+        chunker["chunker (md-heading-v1, pdf-page-v1, code-{rust,python,ts,js,go,java,kotlin,c,cpp}-ast-v1, k8s-manifest-resource-v1, dockerfile-file-v1, manifest-file-v1, code-text-paragraph-v1)"]
         embedder["embedder (fastembed multilingual-e5-large)"]
         retriever["retriever (lexical / vector / hybrid RRF)"]
         rag["RAG pipeline"]

crates/kebab-app/Cargo.toml

@@ -23,6 +23,11 @@ kebab-embed-local = { path = "../kebab-embed-local" }
 kebab-llm = { path = "../kebab-llm" }
 kebab-llm-local = { path = "../kebab-llm-local" }
 kebab-rag = { path = "../kebab-rag" }
+# p9-fb-41 PR-9c-2: facade construction of OnnxNliVerifier when
+# `[rag] nli_threshold > 0`. Trait-only consumption via kebab-rag's
+# `with_verifier`; no kebab-nli internals leak into kebab-app code
+# beyond the construction site in `open_with_config`.
+kebab-nli = { path = "../kebab-nli" }
 # P6-4: image extractor + OCR + caption adapters live here. App
 # threads them into the per-asset dispatch (see `ingest_one_asset`
 # image branch). Trait-only consumption — no `kebab-parse-image`
@@ -76,3 +81,6 @@ lopdf                = "0.32"
 # error_wire::tests::llm_unreachable_classifies_to_model_unreachable needs a real
 # reqwest::Error (private constructor) — built from a connect-refused call.
 reqwest      = { version = "0.12", default-features = false, features = ["blocking", "rustls-tls"] }
+
+[lints]
+workspace = true

crates/kebab-app/src/app.rs

@@ -73,6 +73,37 @@ pub struct SearchResponse {
     /// p9-fb-37: present when caller passed `SearchOpts.trace = true`.
     /// Consumers that ignore trace should leave this `None`.
     pub trace: Option<kebab_core::SearchTrace>,
+    /// v0.17.0 A5 Step 4b: human / agent-readable advisory string set
+    /// when the empty hit list is likely due to a query shorter than the
+    /// FTS5 trigram tokenizer's 3-char minimum. `None` otherwise. CLI
+    /// surfaces it on stderr (text mode); MCP / `--json` consumers
+    /// surface it however they prefer. See
+    /// `docs/superpowers/specs/2026-05-22-korean-trigram-tokenizer-design.md`
+    /// §3.3.
+    pub hint: Option<String>,
+}
+
+/// v0.17.0 A5 Step 4b: decide whether to attach a "3자 이상 키워드 권장"
+/// hint to a `SearchResponse`. Fires only when the result set is empty
+/// *and* the trimmed query is shorter than the trigram tokenizer can
+/// resolve. Raw FTS5 mode (`'...'`) opts out — the user explicitly
+/// invoked FTS5 syntax. Identical condition powers the CLI stderr line
+/// and (separately) the TUI status bar.
+pub fn short_query_hint(query_text: &str, hits_empty: bool) -> Option<String> {
+    if !hits_empty {
+        return None;
+    }
+    let trimmed = query_text.trim();
+    let bytes = trimmed.as_bytes();
+    // Raw single-quote mode: user opted into FTS5 syntax, no advisory.
+    if bytes.len() >= 2 && bytes[0] == b'\'' && bytes[bytes.len() - 1] == b'\'' {
+        return None;
+    }
+    if trimmed.chars().count() < 3 {
+        Some("3자 이상 키워드 권장 (trigram tokenizer 제약)".to_string())
+    } else {
+        None
+    }
 }
 
 /// Facade state — see module docs for lifetime rules.
@@ -102,6 +133,17 @@ pub struct App {
     /// `corpus_revision` snapshot embedded in `SearchCacheKey`
     /// invalidates every entry the moment a new ingest commit lands.
     search_cache: Option<Mutex<LruCache<SearchCacheKey, Vec<SearchHit>>>>,
+    /// p9-fb-41 PR-9c-2: NLI verifier built eagerly at
+    /// `open_with_config` time when `config.rag.nli_threshold > 0`,
+    /// consumed by `RagPipeline::with_verifier` on every `ask` /
+    /// `ask_with_session` call. `None` when the gate is disabled
+    /// (default, threshold = 0) — multi-hop skips step 8.5 entirely
+    /// and single-pass never touches the verifier.
+    ///
+    /// Built eagerly (not lazy) so the `open_with_config` `?`
+    /// propagation surfaces NLI model construction errors at App
+    /// boot time, before any user query runs.
+    pipeline_verifier: Option<Arc<dyn kebab_nli::NliVerifier>>,
 }
 
 /// p9-fb-19: cache key for `App::search`. Includes every field that
@@ -162,6 +204,21 @@ impl App {
         // `None` (cache disabled — every search hits the retrievers).
         let search_cache = NonZeroUsize::new(config.search.cache_capacity)
             .map(|cap| Mutex::new(LruCache::new(cap)));
+        // p9-fb-41 PR-9c-2: build the NLI verifier when the gate is
+        // enabled. App carries it on `RagPipeline` via
+        // `with_verifier` so the rag crate doesn't have to know about
+        // kebab-nli construction. Failure (`?`) surfaces as a user-
+        // facing error at App boot — never a panic in the pipeline's
+        // `expect("verifier must be Some when nli_threshold > 0.0")`.
+        let pipeline_verifier: Option<Arc<dyn kebab_nli::NliVerifier>> =
+            if config.rag.nli_threshold > 0.0 {
+                let v = kebab_nli::OnnxNliVerifier::new(&config).context(
+                    "kebab-app: construct OnnxNliVerifier (config.rag.nli_threshold > 0)",
+                )?;
+                Some(Arc::new(v))
+            } else {
+                None
+            };
         Ok(Self {
             config,
             sqlite: Arc::new(sqlite),
@@ -169,6 +226,7 @@ impl App {
             vector: OnceLock::new(),
             llm: OnceLock::new(),
             search_cache,
+            pipeline_verifier,
         })
     }
 
@@ -235,7 +293,7 @@ impl App {
         // so other in-flight searches can use the cache concurrently.
         drop(guard);
         let hits = self.search_uncached(query)?;
-        let mut guard = cache.lock().unwrap_or_else(|e| e.into_inner());
+        let mut guard = cache.lock().unwrap_or_else(std::sync::PoisonError::into_inner);
         guard.put(key, hits.clone());
         Ok(hits)
     }
@@ -409,7 +467,7 @@ impl App {
 
             // Snippet truncation if opts.snippet_chars set (mirror non-trace path).
             if opts.snippet_chars.is_some() {
-                for h in hits.iter_mut() {
+                for h in &mut hits {
                     if h.snippet.chars().count() > snippet_chars {
                         h.snippet = trim_to_chars(&h.snippet, snippet_chars);
                     }
@@ -418,11 +476,13 @@ impl App {
 
             // Trace path skips the budget loop. Caller will inspect
             // `hits.len()` and `trace.timing` rather than paginate.
+            let hint = short_query_hint(&query.text, hits.is_empty());
             return Ok(SearchResponse {
                 hits,
                 next_cursor: None,
                 truncated: false,
                 trace: Some(trace),
+                hint,
             });
         }
 
@@ -442,7 +502,7 @@ impl App {
         // `config.search.snippet_chars`; this only kicks in when the
         // caller asked for *less*).
         if opts.snippet_chars.is_some() {
-            for h in hits.iter_mut() {
+            for h in &mut hits {
                 if h.snippet.chars().count() > snippet_chars {
                     h.snippet = trim_to_chars(&h.snippet, snippet_chars);
                 }
@@ -461,7 +521,7 @@ impl App {
             {
                 current_snippet_cap =
                     (current_snippet_cap / 2).max(SNIPPET_FLOOR);
-                for h in hits.iter_mut() {
+                for h in &mut hits {
                     if h.snippet.chars().count() > current_snippet_cap {
                         h.snippet =
                             trim_to_chars(&h.snippet, current_snippet_cap);
@@ -505,11 +565,13 @@ impl App {
             None
         };
 
+        let hint = short_query_hint(&query.text, hits.is_empty());
         Ok(SearchResponse {
             hits,
             next_cursor,
             truncated,
             trace: None,
+            hint,
         })
     }
 
@@ -518,9 +580,26 @@ impl App {
     pub fn ask(&self, query: &str, opts: AskOpts) -> Result<Answer> {
         let retriever = self.build_retriever(opts.mode)?;
         let llm = self.llm()?;
+        let pipeline = self.build_pipeline(retriever, llm);
+        pipeline.ask(query, opts)
+    }
+
+    /// p9-fb-41 PR-9c-2: shared pipeline builder used by [`Self::ask`]
+    /// and [`Self::ask_with_session`]. Attaches the App-built NLI
+    /// verifier (when `cfg.rag.nli_threshold > 0`) via
+    /// `RagPipeline::with_verifier`, keeping the construction site in
+    /// a single place so the two call paths can't drift.
+    fn build_pipeline(
+        &self,
+        retriever: Arc<dyn Retriever>,
+        llm: Arc<dyn LanguageModel>,
+    ) -> RagPipeline {
         let pipeline =
             RagPipeline::new(self.config.clone(), retriever, llm, self.sqlite.clone());
-        pipeline.ask(query, opts)
+        match &self.pipeline_verifier {
+            Some(v) => pipeline.with_verifier(v.clone()),
+            None => pipeline,
+        }
     }
 
     /// p9-fb-18: shared retriever-stack builder used by [`Self::ask`]
@@ -625,10 +704,11 @@ impl App {
 
         // p9-fb-18 R1: shared retriever builder removes the prior
         // copy of `ask`'s 35-line stack — see [`Self::build_retriever`].
+        // p9-fb-41 PR-9c-2: shared `build_pipeline` attaches the NLI
+        // verifier when the gate is enabled.
         let retriever = self.build_retriever(opts.mode)?;
         let llm = self.llm()?;
-        let pipeline =
-            RagPipeline::new(self.config.clone(), retriever, llm, self.sqlite.clone());
+        let pipeline = self.build_pipeline(retriever, llm);
         let answer = pipeline.ask_with_history(
             query,
             history,
@@ -788,7 +868,7 @@ impl App {
     /// clear` admin command). No-op when the cache is disabled.
     pub fn clear_search_cache(&self) {
         if let Some(cache) = self.search_cache.as_ref() {
-            let mut guard = cache.lock().unwrap_or_else(|e| e.into_inner());
+            let mut guard = cache.lock().unwrap_or_else(std::sync::PoisonError::into_inner);
             guard.clear();
         }
     }

crates/kebab-app/src/bulk.rs

@@ -96,6 +96,11 @@ fn serialize_search_response(r: &SearchResponse) -> Value {
             None => Value::Null,
         };
         map.insert("trace".to_string(), trace_v);
+        // v0.17.0 A5 Step 4b: only emit `hint` when set — matches
+        // the CLI wire wrapper's additive emit pattern.
+        if let Some(hint) = &r.hint {
+            map.insert("hint".to_string(), Value::String(hint.clone()));
+        }
     }
     v
 }
@@ -134,9 +139,8 @@ fn parse_one(raw: &Value) -> Result<(SearchQuery, SearchOpts), String> {
 
     let k = obj
         .get("k")
-        .and_then(|v| v.as_u64())
-        .map(|n| n as usize)
-        .unwrap_or(0); // 0 → use config default in app
+        .and_then(serde_json::Value::as_u64)
+        .map_or(0, |n| n as usize); // 0 → use config default in app
 
     let trust_min = match obj.get("trust_min").and_then(|v| v.as_str()) {
         None => None,
@@ -204,14 +208,14 @@ fn parse_one(raw: &Value) -> Result<(SearchQuery, SearchOpts), String> {
     let opts = SearchOpts {
         max_tokens: obj
             .get("max_tokens")
-            .and_then(|v| v.as_u64())
+            .and_then(serde_json::Value::as_u64)
             .map(|n| n as usize),
         snippet_chars: obj
             .get("snippet_chars")
-            .and_then(|v| v.as_u64())
+            .and_then(serde_json::Value::as_u64)
             .map(|n| n as usize),
         cursor: obj.get("cursor").and_then(|v| v.as_str()).map(String::from),
-        trace: obj.get("trace").and_then(|v| v.as_bool()).unwrap_or(false),
+        trace: obj.get("trace").and_then(serde_json::Value::as_bool).unwrap_or(false),
     };
 
     Ok((

crates/kebab-app/src/error_wire.rs

@@ -91,7 +91,7 @@ pub fn classify(err: &anyhow::Error, verbose: bool) -> ErrorV1 {
     }
     let mut details = json!({});
     if verbose {
-        let chain: Vec<String> = err.chain().map(|c| c.to_string()).collect();
+        let chain: Vec<String> = err.chain().map(std::string::ToString::to_string).collect();
         details = json!({"chain": chain});
     }
     ErrorV1 {

crates/kebab-app/src/external.rs

@@ -50,7 +50,7 @@ pub fn ensure_kebabignore_entry(workspace_root: &Path) -> Result<()> {
     if !existing.is_empty() && !existing.ends_with('\n') {
         file.write_all(b"\n")?;
     }
-    writeln!(file, "{}", KEBABIGNORE_LINE)?;
+    writeln!(file, "{KEBABIGNORE_LINE}")?;
     Ok(())
 }
 

crates/kebab-app/src/ingest_progress.rs

@@ -166,8 +166,8 @@ mod tests {
         };
         let v = serde_json::to_value(&ev).unwrap();
         assert_eq!(v.get("kind").and_then(|s| s.as_str()), Some("asset_started"));
-        assert_eq!(v.get("idx").and_then(|n| n.as_u64()), Some(1));
-        assert_eq!(v.get("total").and_then(|n| n.as_u64()), Some(10));
+        assert_eq!(v.get("idx").and_then(serde_json::Value::as_u64), Some(1));
+        assert_eq!(v.get("total").and_then(serde_json::Value::as_u64), Some(10));
         assert_eq!(v.get("path").and_then(|s| s.as_str()), Some("notes/foo.md"));
         assert_eq!(v.get("media").and_then(|s| s.as_str()), Some("markdown"));
     }
@@ -184,8 +184,8 @@ mod tests {
         let v = serde_json::to_value(&ev).unwrap();
         assert_eq!(v.get("kind").and_then(|s| s.as_str()), Some("completed"));
         let counts = v.get("counts").unwrap();
-        assert_eq!(counts.get("scanned").and_then(|n| n.as_u64()), Some(5));
-        assert_eq!(counts.get("new").and_then(|n| n.as_u64()), Some(2));
+        assert_eq!(counts.get("scanned").and_then(serde_json::Value::as_u64), Some(5));
+        assert_eq!(counts.get("new").and_then(serde_json::Value::as_u64), Some(2));
     }
 
     #[test]

crates/kebab-app/src/lib.rs

@@ -39,7 +39,7 @@ use std::sync::Arc;
 use anyhow::{Context, anyhow};
 use serde::{Deserialize, Serialize};
 
-use kebab_chunk::{CodeGoAstV1Chunker, CodeJavaAstV1Chunker, CodeJsAstV1Chunker, CodeKotlinAstV1Chunker, CodePythonAstV1Chunker, CodeRustAstV1Chunker, CodeTsAstV1Chunker, DockerfileFileV1Chunker, K8sManifestResourceV1Chunker, ManifestFileV1Chunker, MdHeadingV1Chunker, PdfPageV1Chunker};
+use kebab_chunk::{CodeCAstV1Chunker, CodeCppAstV1Chunker, CodeGoAstV1Chunker, CodeJavaAstV1Chunker, CodeJsAstV1Chunker, CodeKotlinAstV1Chunker, CodePythonAstV1Chunker, CodeRustAstV1Chunker, CodeTextParagraphV1Chunker, CodeTsAstV1Chunker, DockerfileFileV1Chunker, K8sManifestResourceV1Chunker, ManifestFileV1Chunker, MdHeadingV1Chunker, PdfPageV1Chunker};
 use kebab_core::{
     Answer, Block, CanonicalDocument, Chunk, ChunkId, ChunkPolicy, ChunkerVersion, Chunker,
     DocFilter, DocSummary, DocumentId, DocumentStore, Embedder, EmbeddingInput,
@@ -50,7 +50,7 @@ use kebab_core::{
 use kebab_llm_local::OllamaLanguageModel;
 use kebab_normalize::build_canonical_document;
 use kebab_parse_image::{ImageExtractor, OllamaVisionOcr, apply_caption, apply_ocr};
-use kebab_parse_code::{GoAstExtractor, JavaAstExtractor, JavascriptAstExtractor, KotlinAstExtractor, PythonAstExtractor, RustAstExtractor, TypescriptAstExtractor};
+use kebab_parse_code::{CAstExtractor, CppAstExtractor, GoAstExtractor, JavaAstExtractor, JavascriptAstExtractor, KotlinAstExtractor, PythonAstExtractor, RustAstExtractor, TypescriptAstExtractor};
 use kebab_parse_pdf::PdfTextExtractor;
 use kebab_parse_md::{BodyHints, parse_blocks, parse_frontmatter};
 use kebab_source_fs::FsSourceConnector;
@@ -69,7 +69,7 @@ pub mod reset;
 pub mod schema;
 mod staleness;
 
-pub use app::{App, SearchResponse};
+pub use app::{App, SearchResponse, short_query_hint};
 pub use ingest_progress::{AggregateCounts, IngestEvent, render_skipped_breakdown};
 pub use reset::{ResetReport, ResetScope, enumerate_orphans};
 pub use error_wire::{ERROR_V1_ID, ErrorV1, StructuredError, classify};
@@ -289,8 +289,7 @@ pub fn ingest_with_config_opts(
     let cancelled = || {
         opts.cancel
             .as_ref()
-            .map(|c| c.load(std::sync::atomic::Ordering::Relaxed))
-            .unwrap_or(false)
+            .is_some_and(|c| c.load(std::sync::atomic::Ordering::Relaxed))
     };
     let force_reingest = opts.force_reingest;
     let started_instant = std::time::Instant::now();
@@ -394,7 +393,7 @@ pub fn ingest_with_config_opts(
     let purged_deleted_files = sweep_deleted_files(
         &app,
         &scanned_paths,
-        vector_store.as_ref().map(|v| v.as_ref()),
+        vector_store.as_ref().map(std::convert::AsRef::as_ref),
     )?;
 
     let started_at = time::OffsetDateTime::now_utc();
@@ -509,10 +508,10 @@ pub fn ingest_with_config_opts(
                 *skipped_by_extension.entry(ext).or_insert(0) += 1;
             }
             kebab_core::IngestItemKind::Unchanged => {
-                unchanged_count = unchanged_count.saturating_add(1)
+                unchanged_count = unchanged_count.saturating_add(1);
             }
             kebab_core::IngestItemKind::Error => {
-                error_count = error_count.saturating_add(1)
+                error_count = error_count.saturating_add(1);
             }
         }
         crate::ingest_progress::emit(
@@ -795,6 +794,7 @@ fn try_skip_unchanged(
     current_chunker_version: &ChunkerVersion,
     current_embedding_version: Option<&kebab_core::EmbeddingVersion>,
     force_reingest: bool,
+    fallback_chunker_version: Option<&ChunkerVersion>, // p10-3 fix
 ) -> anyhow::Result<Option<kebab_core::IngestItem>> {
     if force_reingest {
         return Ok(None);
@@ -829,12 +829,72 @@ fn try_skip_unchanged(
     if existing_doc.source_asset_id != asset.asset_id {
         return Ok(None);
     }
+    // p10-3 fix: detect "stored doc was previously Tier 3 fallback".
+    // When a Tier 1/2 extractor emits empty chunks, the fallback wrapper
+    // retries with CodeTextParagraphV1Chunker and stores
+    // last_chunker_version = "code-text-paragraph-v1" + parser_version = "none-v1".
+    // On the next ingest the caller computes current_parser_version /
+    // current_chunker_version from the Tier 1/2 dispatch (e.g.
+    // "k8s-manifest-resource-v1"), which can never match the stored
+    // fallback values, causing spurious re-ingests. Detect this case
+    // and bypass the parser/chunker equality checks — only the embedder
+    // version still must match.
+    let stored_is_tier3_fallback = fallback_chunker_version.is_some_and(|fbv| {
+        existing_doc.last_chunker_version.as_ref() == Some(fbv)
+            && existing_doc.parser_version.0 == "none-v1"
+    });
+
+    if stored_is_tier3_fallback {
+        // Embedder version still must match.
+        let embedder_match = existing_doc.last_embedding_version.as_ref()
+            == current_embedding_version;
+        if !embedder_match {
+            return Ok(None);
+        }
+        let candidate_doc_id = existing_doc.doc_id.clone();
+        tracing::debug!(
+            target: "kebab-app::ingest",
+            path = %asset.workspace_path.0,
+            doc_id = %candidate_doc_id.0,
+            "skip-unchanged: tier 3 fallback state detected; bypassing parser/chunker equality"
+        );
+        return Ok(Some(kebab_core::IngestItem {
+            kind: kebab_core::IngestItemKind::Unchanged,
+            doc_id: Some(candidate_doc_id),
+            doc_path: asset.workspace_path.clone(),
+            asset_id: Some(asset.asset_id.clone()),
+            byte_len: Some(asset.byte_len),
+            block_count: u32::try_from(existing_doc.blocks.len()).ok(),
+            chunk_count: None,
+            parser_version: Some(existing_doc.parser_version.clone()),
+            chunker_version: existing_doc.last_chunker_version.clone(),
+            warnings: Vec::new(),
+            error: None,
+        }));
+    }
+
     // 2. Parser unchanged: parser_version is baked into id_for_doc so
     //    a version bump yields a different doc_id and the row above
     //    would have been missing. Checking here explicitly keeps the
     //    logic self-documenting and guards against future id_for_doc
     //    changes.
     if existing_doc.parser_version != *current_parser_version {
+        // v0.17.0 PR-B: parser_version bump cascade. Same bytes (same
+        // asset_id) → asset-keyed `stale_chunk_ids_at` is a no-op, but
+        // the stale `documents` row at this workspace_path still
+        // collides with `idx_docs_workspace_path` on the next INSERT
+        // and the LanceDB rows under the old chunk_ids orphan. Sweep
+        // both stores here, before returning Ok(None), so the caller's
+        // full-ingest path lands a clean slate. The `keep_doc_id = ""`
+        // sentinel removes every doc at this path (the new doc_id is
+        // not yet known here — it's computed downstream from the new
+        // PARSER_VERSION).
+        purge_workspace_path_for_parser_bump(app, asset).with_context(|| {
+            format!(
+                "parser-bump orphan purge at {}",
+                asset.workspace_path.0
+            )
+        })?;
         return Ok(None);
     }
     // 3. Chunker unchanged.
@@ -879,9 +939,7 @@ fn try_skip_unchanged(
 fn ext_for_skip_warning(path: &str) -> String {
     std::path::Path::new(path)
         .extension()
-        .and_then(|s| s.to_str())
-        .map(|s| s.to_ascii_lowercase())
-        .unwrap_or_else(|| NO_EXT_SENTINEL.to_string())
+        .and_then(|s| s.to_str()).map_or_else(|| NO_EXT_SENTINEL.to_string(), str::to_ascii_lowercase)
 }
 
 /// p9-fb-25: render the `IngestItem.warnings` line for a Skipped
@@ -948,11 +1006,12 @@ fn ingest_one_asset(
                 force_reingest,
             );
         }
-        // p10-1A-2 / 1B: code ingest dispatch. p10-2: Tier 2 langs added.
+        // p10-1A-2 / 1B: code ingest dispatch. p10-2: Tier 2 langs added. p10-3: shell added. p10-1D: c/cpp added.
         MediaType::Code(lang)
             if matches!(lang.as_str(),
                 "rust" | "python" | "typescript" | "javascript" | "go" | "java" | "kotlin"
-                | "yaml" | "dockerfile" | "toml" | "json" | "xml" | "groovy" | "go-mod") =>
+                | "yaml" | "dockerfile" | "toml" | "json" | "xml" | "groovy" | "go-mod"
+                | "shell" | "c" | "cpp") =>
         {
             return ingest_one_code_asset(
                 app,
@@ -1016,6 +1075,7 @@ fn ingest_one_asset(
         &MdHeadingV1Chunker.chunker_version(),
         embedder.map(|e| e.model_version()).as_ref(),
         force_reingest,
+        None,
     )? {
         return Ok(item);
     }
@@ -1210,6 +1270,7 @@ fn ingest_one_image_asset(
         &MdHeadingV1Chunker.chunker_version(),
         embedder.map(|e| e.model_version()).as_ref(),
         force_reingest,
+        None,
     )? {
         return Ok(item);
     }
@@ -1438,6 +1499,53 @@ fn record_image_analysis_failure(
     warning_notes.push(note);
 }
 
+/// v0.17.0 PR-B: parser-bump cascade. When a code extractor ships a
+/// new `PARSER_VERSION` (e.g. `code-c-v1` → `code-c-v2`), the same
+/// (workspace_path, asset_id) pair re-emerges with a fresh `doc_id`.
+/// The existing asset-keyed [`purge_vector_orphans_for_workspace_path`]
+/// only fires on asset_id changes (file bytes edited) and is a no-op
+/// here. Without an explicit doc-keyed sweep the next INSERT raises
+/// `idx_docs_workspace_path` UNIQUE and the LanceDB rows under the
+/// stale chunk_ids orphan. This helper:
+///
+/// 1. Fetches every stale chunk_id at `workspace_path` from SQLite
+///    (`keep_doc_id = ""` means "all existing docs are stale" —
+///    `try_skip_unchanged` calls this before the new doc_id is
+///    computed).
+/// 2. Deletes the matching vectors from every Lance table (no-op if
+///    embeddings are disabled).
+/// 3. Sweeps the SQLite `documents` row (CASCADE drops `blocks` /
+///    `chunks` / `embedding_records`). The `assets` row stays — same
+///    bytes, same asset_id, only the derived `doc_id` changed.
+fn purge_workspace_path_for_parser_bump(
+    app: &App,
+    asset: &RawAsset,
+) -> anyhow::Result<()> {
+    let path = &asset.workspace_path.0;
+    let stale = app
+        .sqlite
+        .stale_chunk_ids_for_workspace_path_except_doc_id(path, "")
+        .context("SqliteStore::stale_chunk_ids_for_workspace_path_except_doc_id")?;
+    if !stale.is_empty() {
+        if let Some(vec_store) = app.vector().context("App::vector")? {
+            use kebab_core::VectorStore as _;
+            vec_store
+                .delete_by_chunk_ids(&stale)
+                .context("VectorStore::delete_by_chunk_ids (parser-bump orphans)")?;
+        }
+    }
+    app.sqlite
+        .purge_document_at_workspace_path_except_doc_id(path, "")
+        .context("SqliteStore::purge_document_at_workspace_path_except_doc_id")?;
+    tracing::debug!(
+        target: "kebab-app",
+        path = %path,
+        count = stale.len(),
+        "purged orphan vectors + document for parser_version bump"
+    );
+    Ok(())
+}
+
 /// HOTFIXES 2026-05-02 P7-3 follow-up: when a tracked file's bytes
 /// change, `purge_orphan_at_workspace_path` (in `kebab-store-sqlite`)
 /// sweeps the SQLite chain (documents → blocks / chunks / embedding_records)
@@ -1656,6 +1764,7 @@ fn ingest_one_pdf_asset(
         &PdfPageV1Chunker.chunker_version(),
         embedder.map(|e| e.model_version()).as_ref(),
         force_reingest,
+        None,
     )? {
         return Ok(item);
     }
@@ -1835,11 +1944,16 @@ fn ingest_one_code_asset(
         // p10-2: Tier 2 has no parse step — sentinel "none-v1".
         "yaml" | "dockerfile" | "toml" | "json" | "xml" | "groovy" | "go-mod"
             => ParserVersion("none-v1".to_string()),
+        // p10-3: shell direct routes to Tier 3 (no parse step).
+        "shell" => ParserVersion("none-v1".to_string()),
+        // p10-1D: C + C++ AST extractors.
+        "c"   => ParserVersion(kebab_parse_code::C_PARSER_VERSION.to_string()),
+        "cpp" => ParserVersion(kebab_parse_code::CPP_PARSER_VERSION.to_string()),
         other => anyhow::bail!("unsupported code_lang: {other}"),
     };
 
     // p10-1b Task D/G/J/L: chunker_version per-lang.
-    let chunker_version = match code_lang {
+    let mut chunker_version = match code_lang {
         "rust"       => CodeRustAstV1Chunker.chunker_version(),
         "python"     => CodePythonAstV1Chunker.chunker_version(),
         "typescript" => CodeTsAstV1Chunker.chunker_version(),
@@ -1852,9 +1966,26 @@ fn ingest_one_code_asset(
         "dockerfile" => DockerfileFileV1Chunker.chunker_version(),
         "toml" | "json" | "xml" | "groovy" | "go-mod"
                      => ManifestFileV1Chunker.chunker_version(),
+        // p10-3:
+        "shell"      => CodeTextParagraphV1Chunker.chunker_version(),
+        // p10-1D: C + C++ AST chunkers.
+        "c"          => CodeCAstV1Chunker.chunker_version(),
+        "cpp"        => CodeCppAstV1Chunker.chunker_version(),
         other => anyhow::bail!("unreachable chunker_version: {other}"),
     };
 
+    // p10-3 fix: if this lang can fall back to Tier 3, compute the fallback
+    // chunker_version so try_skip_unchanged can detect the stored-as-Tier-3
+    // state and skip parser/chunker equality checks.
+    let tier3_fallback_cv: Option<ChunkerVersion> = match code_lang {
+        "rust" | "python" | "typescript" | "javascript"
+        | "go" | "java" | "kotlin"
+        | "yaml" | "dockerfile" | "toml" | "json" | "xml" | "groovy" | "go-mod"
+        | "c" | "cpp" // p10-1D
+            => Some(CodeTextParagraphV1Chunker.chunker_version()),
+        _ => None,
+    };
+
     if let Some(item) = try_skip_unchanged(
         app,
         asset,
@@ -1862,6 +1993,7 @@ fn ingest_one_code_asset(
         &chunker_version,
         embedder.map(|e| e.model_version()).as_ref(),
         force_reingest,
+        tier3_fallback_cv.as_ref(),
     )? {
         return Ok(item);
     }
@@ -1877,70 +2009,159 @@ fn ingest_one_code_asset(
     };
 
     // p10-1b Task D/G/J/L: extractor per-lang.
-    let mut canonical = match code_lang {
+    // p10-3: capture Result so Tier 1 extractor errors can fall back to Tier 3.
+    let canonical_result: anyhow::Result<kebab_core::CanonicalDocument> = match code_lang {
         "rust" => RustAstExtractor::new()
             .extract(&ctx, &bytes)
-            .context("kb-parse-code::RustAstExtractor::extract (code:rust)")?,
+            .context("kb-parse-code::RustAstExtractor::extract (code:rust)"),
         "python" => PythonAstExtractor::new()
             .extract(&ctx, &bytes)
-            .context("kb-parse-code::PythonAstExtractor::extract (code:python)")?,
+            .context("kb-parse-code::PythonAstExtractor::extract (code:python)"),
         "typescript" => TypescriptAstExtractor::new()
             .extract(&ctx, &bytes)
-            .context("kb-parse-code::TypescriptAstExtractor::extract (code:typescript)")?,
+            .context("kb-parse-code::TypescriptAstExtractor::extract (code:typescript)"),
         "javascript" => JavascriptAstExtractor::new()
             .extract(&ctx, &bytes)
-            .context("kb-parse-code::JavascriptAstExtractor::extract (code:javascript)")?,
+            .context("kb-parse-code::JavascriptAstExtractor::extract (code:javascript)"),
         "go" => GoAstExtractor::new()
             .extract(&ctx, &bytes)
-            .context("kb-parse-code::GoAstExtractor::extract (code:go)")?,
+            .context("kb-parse-code::GoAstExtractor::extract (code:go)"),
         "java" => JavaAstExtractor::new()
             .extract(&ctx, &bytes)
-            .context("kb-parse-code::JavaAstExtractor::extract (code:java)")?,
+            .context("kb-parse-code::JavaAstExtractor::extract (code:java)"),
         "kotlin" => KotlinAstExtractor::new()
             .extract(&ctx, &bytes)
-            .context("kb-parse-code::KotlinAstExtractor::extract (code:kotlin)")?,
+            .context("kb-parse-code::KotlinAstExtractor::extract (code:kotlin)"),
         // p10-2 Tier 2: no extractor — synthesize Document directly from raw bytes.
         "yaml" | "dockerfile" | "toml" | "json" | "xml" | "groovy" | "go-mod" => {
-            synthesize_tier2_document(asset, &bytes, code_lang, &parser_version)?
+            synthesize_tier2_document(asset, &bytes, code_lang, &parser_version)
         }
+        // p10-3: shell reuses the same synthesizer.
+        "shell" => synthesize_tier2_document(asset, &bytes, "shell", &parser_version),
+        // p10-1D: C + C++ AST extractors.
+        "c" => CAstExtractor::new()
+            .extract(&ctx, &bytes)
+            .context("kebab-parse-code::CAstExtractor::extract (code:c)"),
+        "cpp" => CppAstExtractor::new()
+            .extract(&ctx, &bytes)
+            .context("kebab-parse-code::CppAstExtractor::extract (code:cpp)"),
         other => anyhow::bail!("unreachable (extract): {other}"),
     };
 
+    // p10-3: Tier 1 extractor failure → fall back to Tier 3 synthesized doc.
+    // Tier 2 (yaml/dockerfile/…) and shell errors are real (e.g. non-UTF-8) — propagate.
+    let mut canonical = match canonical_result {
+        Ok(d) => d,
+        Err(e) if code_lang == "shell"
+            || matches!(code_lang, "yaml" | "dockerfile" | "toml" | "json" | "xml" | "groovy" | "go-mod") =>
+        {
+            return Err(e).context("synthesize_tier2_document failed for tier 2/3 lang");
+        }
+        Err(e) => {
+            // Tier 1 extractor errored — fall back to Tier 3 synthesized doc.
+            tracing::warn!(
+                workspace_path = %asset.workspace_path.0,
+                code_lang = code_lang,
+                error = %e,
+                "tier1 extract errored; falling back to tier 3 synthesized doc"
+            );
+            chunker_version = CodeTextParagraphV1Chunker.chunker_version();
+            let tier3_parser_version = ParserVersion("none-v1".to_string());
+            synthesize_tier2_document(asset, &bytes, code_lang, &tier3_parser_version)
+                .context("synthesize_tier2_document for tier 3 fallback after extract error")?
+        }
+    };
+
     // p10-1b Task D/G/J/L: chunker per-lang.
-    let chunks = match code_lang {
-        "rust" => CodeRustAstV1Chunker
+    // p10-3: track whether the extract stage already fell back to Tier 3.
+    // Tier 2 langs already have "none-v1" parser_version normally, so exclude them
+    // from the extract_fell_back guard with the !matches! exclusion.
+    let extract_fell_back = canonical.parser_version.0 == "none-v1"
+        && !matches!(code_lang, "yaml" | "dockerfile" | "toml" | "json" | "xml" | "groovy" | "go-mod" | "shell");
+
+    let chunks_result: anyhow::Result<Vec<Chunk>> = if extract_fell_back {
+        // Tier 1 lang whose extractor errored — go straight to Tier 3 chunker.
+        CodeTextParagraphV1Chunker
             .chunk(&canonical, chunk_policy)
-            .context("kb-chunk::CodeRustAstV1Chunker::chunk (code:rust)")?,
-        "python" => CodePythonAstV1Chunker
-            .chunk(&canonical, chunk_policy)
-            .context("kb-chunk::CodePythonAstV1Chunker::chunk (code:python)")?,
-        "typescript" => CodeTsAstV1Chunker
-            .chunk(&canonical, chunk_policy)
-            .context("kb-chunk::CodeTsAstV1Chunker::chunk (code:typescript)")?,
-        "javascript" => CodeJsAstV1Chunker
-            .chunk(&canonical, chunk_policy)
-            .context("kb-chunk::CodeJsAstV1Chunker::chunk (code:javascript)")?,
-        "go" => CodeGoAstV1Chunker
-            .chunk(&canonical, chunk_policy)
-            .context("kb-chunk::CodeGoAstV1Chunker::chunk (code:go)")?,
-        "java" => CodeJavaAstV1Chunker
-            .chunk(&canonical, chunk_policy)
-            .context("kb-chunk::CodeJavaAstV1Chunker::chunk (code:java)")?,
-        "kotlin"     => CodeKotlinAstV1Chunker
-            .chunk(&canonical, chunk_policy)
-            .context("kb-chunk::CodeKotlinAstV1Chunker::chunk (code:kotlin)")?,
-        // p10-2 Tier 2:
-        "yaml"       => K8sManifestResourceV1Chunker
-            .chunk(&canonical, chunk_policy)
-            .context("kb-chunk::K8sManifestResourceV1Chunker::chunk")?,
-        "dockerfile" => DockerfileFileV1Chunker
-            .chunk(&canonical, chunk_policy)
-            .context("kb-chunk::DockerfileFileV1Chunker::chunk")?,
-        "toml" | "json" | "xml" | "groovy" | "go-mod"
-                     => ManifestFileV1Chunker
-            .chunk(&canonical, chunk_policy)
-            .context("kb-chunk::ManifestFileV1Chunker::chunk")?,
-        other => anyhow::bail!("unreachable (chunk): {other}"),
+            .context("kb-chunk::CodeTextParagraphV1Chunker::chunk (tier 3 after extract fallback)")
+    } else {
+        match code_lang {
+            "rust" => CodeRustAstV1Chunker
+                .chunk(&canonical, chunk_policy)
+                .context("kb-chunk::CodeRustAstV1Chunker::chunk (code:rust)"),
+            "python" => CodePythonAstV1Chunker
+                .chunk(&canonical, chunk_policy)
+                .context("kb-chunk::CodePythonAstV1Chunker::chunk (code:python)"),
+            "typescript" => CodeTsAstV1Chunker
+                .chunk(&canonical, chunk_policy)
+                .context("kb-chunk::CodeTsAstV1Chunker::chunk (code:typescript)"),
+            "javascript" => CodeJsAstV1Chunker
+                .chunk(&canonical, chunk_policy)
+                .context("kb-chunk::CodeJsAstV1Chunker::chunk (code:javascript)"),
+            "go" => CodeGoAstV1Chunker
+                .chunk(&canonical, chunk_policy)
+                .context("kb-chunk::CodeGoAstV1Chunker::chunk (code:go)"),
+            "java" => CodeJavaAstV1Chunker
+                .chunk(&canonical, chunk_policy)
+                .context("kb-chunk::CodeJavaAstV1Chunker::chunk (code:java)"),
+            "kotlin" => CodeKotlinAstV1Chunker
+                .chunk(&canonical, chunk_policy)
+                .context("kb-chunk::CodeKotlinAstV1Chunker::chunk (code:kotlin)"),
+            // p10-2 Tier 2:
+            "yaml" => K8sManifestResourceV1Chunker
+                .chunk(&canonical, chunk_policy)
+                .context("kb-chunk::K8sManifestResourceV1Chunker::chunk"),
+            "dockerfile" => DockerfileFileV1Chunker
+                .chunk(&canonical, chunk_policy)
+                .context("kb-chunk::DockerfileFileV1Chunker::chunk"),
+            "toml" | "json" | "xml" | "groovy" | "go-mod" => ManifestFileV1Chunker
+                .chunk(&canonical, chunk_policy)
+                .context("kb-chunk::ManifestFileV1Chunker::chunk"),
+            // p10-3:
+            "shell" => CodeTextParagraphV1Chunker
+                .chunk(&canonical, chunk_policy)
+                .context("kb-chunk::CodeTextParagraphV1Chunker::chunk (code:shell)"),
+            // p10-1D: C + C++ AST chunkers.
+            "c" => CodeCAstV1Chunker
+                .chunk(&canonical, chunk_policy)
+                .context("kebab-chunk::CodeCAstV1Chunker::chunk (code:c)"),
+            "cpp" => CodeCppAstV1Chunker
+                .chunk(&canonical, chunk_policy)
+                .context("kebab-chunk::CodeCppAstV1Chunker::chunk (code:cpp)"),
+            other => anyhow::bail!("unreachable (chunk): {other}"),
+        }
+    };
+
+    // p10-3: Tier 1/2 0-chunk OR error → Tier 3 fallback retry.
+    // "shell" direct path is already Tier 3 — don't retry-double-up.
+    let chunks: Vec<Chunk> = match chunks_result {
+        Ok(v) if !v.is_empty() => v,
+        other if code_lang == "shell" => other?,  // shell propagates directly
+        Ok(_empty) => {
+            tracing::warn!(
+                workspace_path = %asset.workspace_path.0,
+                code_lang = code_lang,
+                "tier1/2 emitted 0 chunks; falling back to tier 3 (code-text-paragraph-v1)"
+            );
+            chunker_version = CodeTextParagraphV1Chunker.chunker_version();
+            canonical.parser_version = ParserVersion("none-v1".to_string());
+            CodeTextParagraphV1Chunker
+                .chunk(&canonical, chunk_policy)
+                .context("kb-chunk::CodeTextParagraphV1Chunker::chunk (tier 3 fallback)")?
+        }
+        Err(e) => {
+            tracing::warn!(
+                workspace_path = %asset.workspace_path.0,
+                code_lang = code_lang,
+                error = %e,
+                "tier1/2 chunker errored; falling back to tier 3 (code-text-paragraph-v1)"
+            );
+            chunker_version = CodeTextParagraphV1Chunker.chunker_version();
+            canonical.parser_version = ParserVersion("none-v1".to_string());
+            CodeTextParagraphV1Chunker
+                .chunk(&canonical, chunk_policy)
+                .context("kb-chunk::CodeTextParagraphV1Chunker::chunk (tier 3 fallback after error)")?
+        }
     };
 
     // Stamp chunker + embedding versions so incremental skip detection has
@@ -2101,11 +2322,15 @@ fn synthesize_tier2_document(
         },
     ];
 
-    // Resolve abs path for repo detection (mirrors RustAstExtractor pattern).
-    let workspace_root = std::path::PathBuf::new(); // not needed for detect_repo walk
+    // Resolve absolute path for repo detection. FsSourceConnector always
+    // emits absolute paths in SourceUri::File (verified in connector.rs); Kb
+    // URIs were rejected earlier in ingest_one_code_asset (returns Skipped),
+    // so the fallback below is purely defensive. This does NOT mirror
+    // RustAstExtractor — that extractor joins ctx.workspace_root for relative
+    // paths, but Tier 2 trusts the connector invariant.
     let abs_path = match &asset.source_uri {
         kebab_core::SourceUri::File(p) => p.clone(),
-        kebab_core::SourceUri::Kb(_) => workspace_root,
+        kebab_core::SourceUri::Kb(_) => std::path::PathBuf::new(),
     };
     let (repo, git_branch, git_commit) = match kebab_parse_code::detect_repo(&abs_path) {
         Some(r) => (Some(r.name), r.branch, r.commit),
@@ -2179,7 +2404,7 @@ fn lang_hint_from_doc(doc: &CanonicalDocument) -> Option<Lang> {
 
 /// Convenience: end byte of the frontmatter region (or 0 when absent).
 fn fm_span_end(span: Option<kebab_parse_md::FrontmatterSpan>) -> usize {
-    span.map(|s| s.end).unwrap_or(0)
+    span.map_or(0, |s| s.end)
 }
 
 /// Count `\n` in a byte prefix to convert frontmatter byte span to
@@ -2482,8 +2707,7 @@ pub fn ingest_file_with_config(
     const SUPPORTED_EXTS: &[&str] = &["md", "pdf", "png", "jpg", "jpeg"];
     if !SUPPORTED_EXTS.contains(&ext.as_str()) {
         anyhow::bail!(
-            "ingest-file: unsupported extension `.{}` (supported: {:?})",
-            ext, SUPPORTED_EXTS
+            "ingest-file: unsupported extension `.{ext}` (supported: {SUPPORTED_EXTS:?})"
         );
     }
 

crates/kebab-app/src/schema.rs

@@ -63,14 +63,26 @@ pub struct Stats {
     /// p9-fb-37: docs whose `updated_at` exceeds the staleness threshold.
     #[serde(default)]
     pub stale_doc_count: u64,
-    /// p10-1A-1: code language breakdown (chunk counts by canonical lowercase
-    /// language identifier). Empty until 1A-2 produces code chunks.
+    /// p10-1A-1: code language breakdown (**doc** counts by canonical
+    /// lowercase language identifier). Empty until 1A-2 produces code
+    /// docs. v0.17.0 PR-C: doc-count semantics corrected here (the
+    /// previous "chunk counts" wording was a longstanding mis-label —
+    /// implementation has always been `COUNT(*) FROM documents
+    /// GROUP BY code_lang`). Use `code_lang_chunk_breakdown` for the
+    /// chunk-level companion.
     #[serde(default)]
     pub code_lang_breakdown: std::collections::BTreeMap<String, u32>,
-    /// p10-1A-1: repo breakdown (chunk counts by `metadata.repo` value).
-    /// Empty until 1A-2 produces code chunks.
+    /// p10-1A-1: repo breakdown (**doc** counts by `metadata.repo`
+    /// value). Empty until 1A-2 produces code docs. v0.17.0 PR-C:
+    /// doc-count wording corrected (mirror of code_lang_breakdown).
     #[serde(default)]
     pub repo_breakdown: std::collections::BTreeMap<String, u32>,
+    /// v0.17.0 PR-C: sister of [`Self::code_lang_breakdown`] returning
+    /// chunk counts instead of doc counts. Indexing-pressure metric —
+    /// one PDF spec → 200 chunks vs one Rust file → 5 chunks shows up
+    /// here in a way `code_lang_breakdown` (doc count) hides.
+    #[serde(default)]
+    pub code_lang_chunk_breakdown: std::collections::BTreeMap<String, u32>,
 }
 
 const KEBAB_VERSION: &str = env!("CARGO_PKG_VERSION");
@@ -153,7 +165,7 @@ fn collect_stats(
     store: &kebab_store_sqlite::SqliteStore,
 ) -> anyhow::Result<Stats> {
     let counts = store
-        .count_summary_with_threshold(cfg.search.stale_threshold_days as u64)?;
+        .count_summary_with_threshold(u64::from(cfg.search.stale_threshold_days))?;
     let data_dir = kebab_config::expand_path(&cfg.storage.data_dir, "");
     let index_bytes = kebab_store_sqlite::stats_ext::index_bytes(&data_dir)
         .map_err(|e| anyhow::anyhow!("index_bytes: {e}"))?;
@@ -171,6 +183,9 @@ fn collect_stats(
         // p10-1A-2 follow-up: dogfooding (2026-05-20) revealed this was a
         // placeholder — mirror of code_lang_breakdown for the repo field.
         repo_breakdown: store.repo_breakdown()?,
+        // v0.17.0 PR-C: chunk-level companion (closes HOTFIXES
+        // 2026-05-22 "code_lang_breakdown chunk granularity" LOW).
+        code_lang_chunk_breakdown: store.code_lang_chunk_breakdown()?,
     })
 }
 
@@ -210,6 +225,11 @@ mod tests_stats_ext {
             v.get("repo_breakdown").is_some(),
             "Stats JSON must include repo_breakdown: {v}"
         );
+        // v0.17.0 PR-C: chunk-level companion field.
+        assert!(
+            v.get("code_lang_chunk_breakdown").is_some(),
+            "Stats JSON must include code_lang_chunk_breakdown (v0.17.0 PR-C): {v}"
+        );
         // Empty BTreeMap serializes as `{}` — confirm it's an object, not null.
         assert!(
             v["code_lang_breakdown"].is_object(),
@@ -219,6 +239,10 @@ mod tests_stats_ext {
             v["repo_breakdown"].is_object(),
             "repo_breakdown must be an object: {v}"
         );
+        assert!(
+            v["code_lang_chunk_breakdown"].is_object(),
+            "code_lang_chunk_breakdown must be an object: {v}"
+        );
     }
 
     #[test]

crates/kebab-app/tests/ask_smoke.rs

@@ -33,6 +33,7 @@ fn ask_lexical_smoke() {
         history: Vec::new(),
         conversation_id: None,
         turn_index: None,
+        multi_hop: false,
     };
     // The fixture workspace contains "ownership" content; the model's
     // citation behavior depends on its training, so we don't assert on

crates/kebab-app/tests/code_ingest_smoke.rs

@@ -850,6 +850,181 @@ fn tier2_cargo_toml_ingest_searchable() {
     );
 }
 
+/// p10-3 Task E: a `.sh` file is ingested via the shell direct-Tier-3 path
+/// and the resulting `Citation::Code` hit must carry `lang="shell"`,
+/// `symbol=None`, `line_start >= 1`, and
+/// `chunker_version = "code-text-paragraph-v1"`.
+#[test]
+fn tier3_shell_ingest_searchable() {
+    let env = TestEnv::lexical_only();
+
+    std::fs::write(
+        env.workspace_root.join("deploy.sh"),
+        "#!/usr/bin/env bash\nset -e\necho hello\n\nkebab ingest --json\n",
+    )
+    .unwrap();
+
+    let report = kebab_app::ingest_with_config(env.config.clone(), env.scope(), false)
+        .expect("ingest must succeed");
+    assert_eq!(report.errors, 0, "no ingest errors: {report:?}");
+    assert!(report.new >= 1, "shell file ingested: {report:?}");
+
+    let sh_item = report
+        .items
+        .as_ref()
+        .expect("items present")
+        .iter()
+        .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()),
+        Some("none-v1"),
+        "parser_version must be none-v1 for shell (Tier 3 direct)"
+    );
+    assert_eq!(
+        sh_item.chunker_version.as_ref().map(|c| c.0.as_str()),
+        Some("code-text-paragraph-v1"),
+        "chunker_version must be code-text-paragraph-v1 for shell"
+    );
+
+    let query = kebab_core::SearchQuery {
+        text: "kebab".to_string(),
+        mode: kebab_core::SearchMode::Lexical,
+        k: 10,
+        filters: kebab_core::SearchFilters {
+            code_lang: vec!["shell".to_string()],
+            ..Default::default()
+        },
+    };
+    let hits = kebab_app::search_with_config(env.config.clone(), query)
+        .expect("search must succeed");
+
+    let h = hits
+        .iter()
+        .find(|h| matches!(&h.citation, Citation::Code { .. }))
+        .expect("at least one Citation::Code hit for 'kebab'");
+
+    match &h.citation {
+        Citation::Code {
+            lang,
+            symbol,
+            line_start,
+            ..
+        } => {
+            assert_eq!(
+                lang.as_deref(),
+                Some("shell"),
+                "citation.lang must be 'shell'"
+            );
+            assert_eq!(*symbol, None, "Tier 3 symbol must be None");
+            assert!(*line_start >= 1, "line_start must be >=1");
+        }
+        _ => unreachable!(),
+    }
+
+    assert_eq!(
+        h.code_lang.as_deref(),
+        Some("shell"),
+        "SearchHit.code_lang must be 'shell'"
+    );
+    assert_eq!(
+        h.chunker_version.0.as_str(),
+        "code-text-paragraph-v1",
+        "shell chunks must be stamped with the Tier 3 chunker_version"
+    );
+}
+
+/// p10-3 Task E: a docker-compose-shaped YAML file (no `apiVersion`/`kind`)
+/// is ingested; the k8s chunker returns `Ok(vec![])` and the Tier 3 fallback
+/// wrapper retries with `CodeTextParagraphV1Chunker`. The resulting
+/// `Citation::Code` hit must carry `lang="yaml"`, `symbol=None`,
+/// `line_start >= 1`, and `chunker_version = "code-text-paragraph-v1"`.
+#[test]
+fn tier3_yaml_fallback_picks_up_non_k8s_yaml() {
+    let env = TestEnv::lexical_only();
+
+    // docker-compose-shaped YAML — version + services but no apiVersion/kind.
+    // The k8s chunker returns Ok(vec![]); Tier 3 fallback should pick this up.
+    std::fs::write(
+        env.workspace_root.join("docker-compose.yml"),
+        "version: '3'\nservices:\n  api:\n    image: nginx:latest\n    ports:\n      - 8080:80\n",
+    )
+    .unwrap();
+
+    let report = kebab_app::ingest_with_config(env.config.clone(), env.scope(), false)
+        .expect("ingest must succeed");
+    assert_eq!(report.errors, 0, "no ingest errors: {report:?}");
+    assert!(
+        report.new >= 1,
+        "expected non-k8s yaml ingested via Tier 3, got {} new docs",
+        report.new
+    );
+
+    let yaml_item = report
+        .items
+        .as_ref()
+        .expect("items present")
+        .iter()
+        .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()),
+        Some("none-v1"),
+        "parser_version must be none-v1 after Tier 3 fallback"
+    );
+    assert_eq!(
+        yaml_item.chunker_version.as_ref().map(|c| c.0.as_str()),
+        Some("code-text-paragraph-v1"),
+        "chunker_version must be code-text-paragraph-v1 after Tier 3 fallback"
+    );
+
+    let query = kebab_core::SearchQuery {
+        text: "nginx".to_string(),
+        mode: kebab_core::SearchMode::Lexical,
+        k: 10,
+        filters: kebab_core::SearchFilters {
+            code_lang: vec!["yaml".to_string()],
+            ..Default::default()
+        },
+    };
+    let hits = kebab_app::search_with_config(env.config.clone(), query)
+        .expect("search must succeed");
+
+    let h = hits
+        .iter()
+        .find(|h| matches!(&h.citation, Citation::Code { .. }))
+        .expect("at least one Citation::Code hit for 'nginx'");
+
+    match &h.citation {
+        Citation::Code {
+            lang,
+            symbol,
+            line_start,
+            ..
+        } => {
+            assert_eq!(
+                lang.as_deref(),
+                Some("yaml"),
+                "citation.lang must be 'yaml'"
+            );
+            assert_eq!(*symbol, None, "Tier 3 fallback symbol must be None");
+            assert!(*line_start >= 1, "line_start must be >=1");
+        }
+        _ => unreachable!(),
+    }
+
+    assert_eq!(
+        h.code_lang.as_deref(),
+        Some("yaml"),
+        "SearchHit.code_lang must be 'yaml'"
+    );
+    assert_eq!(
+        h.chunker_version.0.as_str(),
+        "code-text-paragraph-v1",
+        "non-k8s yaml fallback must be stamped code-text-paragraph-v1"
+    );
+}
+
 /// Re-ingesting the same `.rs` file without changes must report
 /// `Unchanged` (incremental-skip path exercised).
 #[test]
@@ -889,3 +1064,328 @@ fn rust_file_re_ingest_is_unchanged() {
     );
     assert_eq!(item2.doc_id, item1.doc_id);
 }
+
+/// p10-3 fix regression: a docker-compose YAML that falls back to Tier 3
+/// (k8s chunker returns empty, CodeTextParagraphV1Chunker retries) must
+/// report Unchanged on the second ingest rather than re-processing.
+/// Before the fix, try_skip_unchanged returned None because the stored
+/// last_chunker_version ("code-text-paragraph-v1" / parser_version
+/// "none-v1") never matched the caller's dispatch values.
+#[test]
+fn tier3_yaml_fallback_reingest_is_unchanged() {
+    let env = TestEnv::lexical_only();
+
+    std::fs::write(
+        env.workspace_root.join("docker-compose.yml"),
+        "version: '3'\nservices:\n  api:\n    image: nginx:latest\n",
+    )
+    .unwrap();
+
+    let report1 =
+        kebab_app::ingest_with_config(env.config.clone(), env.scope(), false)
+            .expect("first ingest");
+    let item1 = report1
+        .items
+        .as_ref()
+        .expect("items present")
+        .iter()
+        .find(|i| i.doc_path.0.ends_with("docker-compose.yml"))
+        .expect("docker-compose.yml in first report");
+    assert!(
+        matches!(item1.kind, IngestItemKind::New),
+        "first ingest must be New, got {:?}", item1.kind
+    );
+    assert_eq!(
+        item1.chunker_version.as_ref().map(|c| c.0.as_str()),
+        Some("code-text-paragraph-v1"),
+        "first ingest must use Tier 3 fallback chunker"
+    );
+
+    let report2 =
+        kebab_app::ingest_with_config(env.config.clone(), env.scope(), false)
+            .expect("second ingest");
+    let item2 = report2
+        .items
+        .as_ref()
+        .expect("items present")
+        .iter()
+        .find(|i| i.doc_path.0.ends_with("docker-compose.yml"))
+        .expect("docker-compose.yml in second report");
+    assert!(
+        matches!(item2.kind, IngestItemKind::Unchanged),
+        "second ingest must be Unchanged, got {:?}", item2.kind
+    );
+}
+
+/// p10-1d Task G: a `.c` file with a single top-level function is ingested
+/// and the resulting `Citation::Code` hit must carry `lang="c"`,
+/// `symbol="parse_record"` (function name only — no nesting in C), and
+/// `chunker_version = "code-c-ast-v1"`.
+#[test]
+fn tier1_c_ingest_searchable() {
+    let env = TestEnv::lexical_only();
+
+    std::fs::write(
+        env.workspace_root.join("parser.c"),
+        "#include <stdio.h>\n\nint parse_record(const char *line) {\n    if (line == NULL) return -1;\n    return 0;\n}\n",
+    )
+    .unwrap();
+
+    let report = kebab_app::ingest_with_config(env.config.clone(), env.scope(), false)
+        .expect("ingest must succeed");
+    assert_eq!(report.errors, 0, "no ingest errors: {report:?}");
+    assert!(report.new >= 1, "c file ingested: {report:?}");
+
+    let c_item = report
+        .items
+        .as_ref()
+        .expect("items present")
+        .iter()
+        .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()),
+        Some("code-c-v2"),
+        "parser_version must be code-c-v2 (v0.17.0 PR-B: typedef-wrapped struct/enum/union 이 typedef alias unit 으로 방출)"
+    );
+    assert_eq!(
+        c_item.chunker_version.as_ref().map(|c| c.0.as_str()),
+        Some("code-c-ast-v1"),
+        "chunker_version must be code-c-ast-v1"
+    );
+
+    let query = kebab_core::SearchQuery {
+        text: "parse_record".to_string(),
+        mode: kebab_core::SearchMode::Lexical,
+        k: 10,
+        filters: kebab_core::SearchFilters {
+            code_lang: vec!["c".to_string()],
+            ..Default::default()
+        },
+    };
+    let hits = kebab_app::search_with_config(env.config.clone(), query)
+        .expect("search must succeed");
+
+    let h = hits
+        .iter()
+        .find(|h| matches!(&h.citation, Citation::Code { .. }))
+        .expect("at least one Citation::Code hit for 'parse_record'");
+
+    match &h.citation {
+        Citation::Code {
+            lang,
+            symbol,
+            line_start,
+            ..
+        } => {
+            assert_eq!(lang.as_deref(), Some("c"), "citation.lang must be 'c'");
+            assert_eq!(
+                symbol.as_deref(),
+                Some("parse_record"),
+                "C symbol must be function name only (no nesting)"
+            );
+            assert!(*line_start >= 1, "line_start must be >=1");
+        }
+        _ => unreachable!(),
+    }
+
+    assert_eq!(
+        h.code_lang.as_deref(),
+        Some("c"),
+        "SearchHit.code_lang must be 'c'"
+    );
+    assert_eq!(
+        h.chunker_version.0.as_str(),
+        "code-c-ast-v1",
+        "C chunks must be stamped with code-c-ast-v1"
+    );
+}
+
+/// p10-1d Task G: a `.cpp` file with nested namespace + class is ingested
+/// and the resulting `Citation::Code` hit must carry `lang="cpp"`, a
+/// `symbol` that starts with `"kebab::chunk::Foo"` (namespace::Class or
+/// namespace::Class::method), and `chunker_version = "code-cpp-ast-v1"`.
+#[test]
+fn tier1_cpp_ingest_searchable() {
+    let env = TestEnv::lexical_only();
+
+    std::fs::write(
+        env.workspace_root.join("chunker.cpp"),
+        "namespace kebab {\nnamespace chunk {\nclass Foo {\npublic:\n    void bar() { /* impl */ }\n};\n}\n}\n",
+    )
+    .unwrap();
+
+    let report = kebab_app::ingest_with_config(env.config.clone(), env.scope(), false)
+        .expect("ingest must succeed");
+    assert_eq!(report.errors, 0, "no ingest errors: {report:?}");
+    assert!(report.new >= 1, "cpp file ingested: {report:?}");
+
+    let cpp_item = report
+        .items
+        .as_ref()
+        .expect("items present")
+        .iter()
+        .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()),
+        Some("code-cpp-v1"),
+        "parser_version must be code-cpp-v1"
+    );
+    assert_eq!(
+        cpp_item.chunker_version.as_ref().map(|c| c.0.as_str()),
+        Some("code-cpp-ast-v1"),
+        "chunker_version must be code-cpp-ast-v1"
+    );
+
+    let query = kebab_core::SearchQuery {
+        text: "bar".to_string(),
+        mode: kebab_core::SearchMode::Lexical,
+        k: 10,
+        filters: kebab_core::SearchFilters {
+            code_lang: vec!["cpp".to_string()],
+            ..Default::default()
+        },
+    };
+    let hits = kebab_app::search_with_config(env.config.clone(), query)
+        .expect("search must succeed");
+
+    let h = hits
+        .iter()
+        .find(|h| matches!(&h.citation, Citation::Code { .. }))
+        .expect("at least one Citation::Code hit for 'bar'");
+
+    match &h.citation {
+        Citation::Code {
+            lang,
+            symbol,
+            line_start,
+            ..
+        } => {
+            assert_eq!(lang.as_deref(), Some("cpp"), "citation.lang must be 'cpp'");
+            // Symbol could be "kebab::chunk::Foo" (class) or "kebab::chunk::Foo::bar"
+            // (method) depending on which chunk ranks first.
+            assert!(
+                symbol.as_deref().is_some_and(|s| s.starts_with("kebab::chunk::Foo")),
+                "C++ symbol must start with namespace::Class prefix, got {symbol:?}"
+            );
+            assert!(*line_start >= 1, "line_start must be >=1");
+        }
+        _ => unreachable!(),
+    }
+
+    assert_eq!(
+        h.code_lang.as_deref(),
+        Some("cpp"),
+        "SearchHit.code_lang must be 'cpp'"
+    );
+    assert_eq!(
+        h.chunker_version.0.as_str(),
+        "code-cpp-ast-v1",
+        "C++ chunks must be stamped with code-cpp-ast-v1"
+    );
+}
+
+/// P10 dogfood regression: a k8s YAML with 2 documents (Deployment + Service
+/// separated by `---`) must ingest without a UNIQUE constraint violation.
+/// Before the fix, push_chunks_with_oversize emitted split_key=None for each
+/// resource, giving every resource chunk the same id_hash → identical chunk_id
+/// → SQLite UNIQUE constraint failure on the second resource.
+#[test]
+fn tier2_k8s_multi_resource_yaml_ingests_without_collision() {
+    let env = TestEnv::lexical_only();
+
+    let k8s_dir = env.workspace_root.join("k8s");
+    std::fs::create_dir_all(&k8s_dir).unwrap();
+    std::fs::write(
+        k8s_dir.join("k8s-multi.yaml"),
+        "apiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: api\n  namespace: prod\nspec:\n  replicas: 2\n---\napiVersion: v1\nkind: Service\nmetadata:\n  name: api\n  namespace: prod\nspec:\n  selector:\n    app: api\n",
+    )
+    .unwrap();
+
+    let report = kebab_app::ingest_with_config(env.config.clone(), env.scope(), false)
+        .expect("ingest must succeed");
+
+    // The bug: this would land in report with an error + UNIQUE constraint message.
+    let item = report
+        .items
+        .as_ref()
+        .expect("items present")
+        .iter()
+        .find(|i| i.doc_path.0.ends_with("k8s-multi.yaml"))
+        .expect("k8s-multi.yaml in report");
+    assert!(
+        item.error.is_none(),
+        "multi-resource k8s yaml must ingest without error, got: {:?}",
+        item.error
+    );
+    assert!(
+        matches!(item.kind, IngestItemKind::New),
+        "expected New, got {:?}",
+        item.kind
+    );
+
+    // Both resources must be searchable (≥2 hits: Deployment/prod/api + Service/prod/api).
+    let query = kebab_core::SearchQuery {
+        text: "api".to_string(),
+        mode: kebab_core::SearchMode::Lexical,
+        k: 10,
+        filters: kebab_core::SearchFilters {
+            code_lang: vec!["yaml".to_string()],
+            ..Default::default()
+        },
+    };
+    let hits = kebab_app::search_with_config(env.config.clone(), query)
+        .expect("search must succeed");
+    assert!(
+        hits.len() >= 2,
+        "expected ≥2 hits (Deployment + Service), got {}",
+        hits.len()
+    );
+}
+
+/// p10-3 fix regression: a shell file (direct Tier 3, not a fallback)
+/// must also report Unchanged on re-ingest. Shell goes straight to
+/// CodeTextParagraphV1Chunker so `stored_is_tier3_fallback` is false
+/// (parser_version is "none-v1" and chunker matches the current dispatch),
+/// but the normal equality path should pass regardless.
+#[test]
+fn tier3_shell_reingest_is_unchanged() {
+    let env = TestEnv::lexical_only();
+
+    std::fs::write(
+        env.workspace_root.join("deploy.sh"),
+        "#!/usr/bin/env bash\nset -e\necho hello\n",
+    )
+    .unwrap();
+
+    let report1 =
+        kebab_app::ingest_with_config(env.config.clone(), env.scope(), false)
+            .expect("first ingest");
+    let item1 = report1
+        .items
+        .as_ref()
+        .expect("items present")
+        .iter()
+        .find(|i| i.doc_path.0.ends_with("deploy.sh"))
+        .expect("deploy.sh in first report");
+    assert!(
+        matches!(item1.kind, IngestItemKind::New),
+        "first ingest must be New, got {:?}", item1.kind
+    );
+
+    let report2 =
+        kebab_app::ingest_with_config(env.config.clone(), env.scope(), false)
+            .expect("second ingest");
+    let item2 = report2
+        .items
+        .as_ref()
+        .expect("items present")
+        .iter()
+        .find(|i| i.doc_path.0.ends_with("deploy.sh"))
+        .expect("deploy.sh in second report");
+    assert!(
+        matches!(item2.kind, IngestItemKind::Unchanged),
+        "shell reingest must be Unchanged, got {:?}", item2.kind
+    );
+}

crates/kebab-app/tests/fetch_integration.rs

@@ -38,12 +38,16 @@ fn fetch_chunk_returns_target_only_when_no_context() {
 #[test]
 fn fetch_chunk_with_context_returns_neighbors() {
     let env = common::TestEnv::new();
-    let body = "# H1\n\nA1\n\n# H2\n\nA2\n\n# H3\n\nA3\n\n# H4\n\nA4\n\n# H5\n\nA5\n";
+    // v0.17.0 trigram tokenizer: terms must be ≥3 Unicode chars to
+    // match. The earlier fixture used 2-char tokens like `A1`/`A3` for
+    // section bodies — those zero-hit under trigram. Use 5-char unique
+    // words per section so the query can pin one chunk deterministically.
+    let body = "# H1\n\napples\n\n# H2\n\nbanana\n\n# H3\n\ncherry\n\n# H4\n\ndurian\n\n# H5\n\nelder\n";
     common::ingest_md(&env, "multi.md", body);
     let app = env.app();
 
     let q = kebab_core::SearchQuery {
-        text: "A3".to_string(),
+        text: "cherry".to_string(),
         mode: kebab_core::SearchMode::Lexical,
         k: 1,
         filters: kebab_core::SearchFilters::default(),

crates/kebab-app/tests/ingest_file.rs

@@ -33,7 +33,7 @@ fn ingest_file_copies_external_md_and_reports_new() {
     assert!(ext_dir.is_dir());
     let entries: Vec<_> = fs::read_dir(&ext_dir)
         .unwrap()
-        .filter_map(|e| e.ok())
+        .filter_map(std::result::Result::ok)
         .collect();
     assert_eq!(entries.len(), 1, "exactly one file in _external/");
     let name = entries[0].file_name().to_string_lossy().into_owned();

crates/kebab-app/tests/ingest_stdin.rs

@@ -35,7 +35,7 @@ fn ingest_stdin_writes_frontmatter_and_reports_new() {
     // _external/ contains exactly one .md file with frontmatter.
     let ext_dir = std::path::PathBuf::from(&cfg.workspace.root).join("_external");
     let entries: Vec<_> = fs::read_dir(&ext_dir).unwrap()
-        .filter_map(|e| e.ok())
+        .filter_map(std::result::Result::ok)
         .collect();
     assert_eq!(entries.len(), 1);
     let content = fs::read_to_string(entries[0].path()).unwrap();
@@ -60,7 +60,7 @@ fn ingest_stdin_without_source_uri() {
 
     let ext_dir = std::path::PathBuf::from(&cfg.workspace.root).join("_external");
     let entries: Vec<_> = fs::read_dir(&ext_dir).unwrap()
-        .filter_map(|e| e.ok())
+        .filter_map(std::result::Result::ok)
         .collect();
     let content = fs::read_to_string(entries[0].path()).unwrap();
     assert!(content.contains("title: \"Title\""));

crates/kebab-app/tests/open_with_config_nli.rs

@@ -0,0 +1,81 @@
+//! Tests for `App::open_with_config`'s NLI verifier construction path.
+//!
+//! Coverage:
+//! 1. `open_with_config_nli_fails_when_model_dir_unwritable_and_threshold_positive` —
+//!    when `rag.nli_threshold > 0` and `storage.model_dir` is unwritable,
+//!    `open_with_config` returns `Err` with "OnnxNliVerifier" in the
+//!    error chain.
+//! 2. `open_with_config_nli_skipped_when_threshold_zero` —
+//!    same bad `model_dir`, but `rag.nli_threshold = 0.0` (gate disabled),
+//!    so `OnnxNliVerifier::new` is never called and `open_with_config`
+//!    succeeds.
+//!
+//! `/proc/1/root` is the init process's filesystem root; on Linux it is
+//! owned by root and not traversable by unprivileged users, making
+//! `create_dir_all` fail with `EACCES` — a reliable "unwritable path"
+//! that requires no test setup beyond the path literal.
+
+use kebab_config::Config;
+
+/// Return a `Config` whose `data_dir` lives in a fresh `TempDir`
+/// (so `SqliteStore::open` succeeds) and whose `model_dir` is set to
+/// `/proc/1/root` (unwritable by non-root processes on Linux).
+///
+/// The `TempDir` is returned alongside the config so the caller keeps
+/// it alive until the test completes — dropping it early would delete
+/// the data directory before any assertions run.
+fn config_with_unwritable_model_dir() -> (tempfile::TempDir, Config) {
+    let tmp = tempfile::tempdir().expect("tempdir");
+    let mut cfg = Config::defaults();
+    // Valid data_dir → SqliteStore::open + run_migrations succeed.
+    cfg.storage.data_dir = tmp.path().to_string_lossy().into_owned();
+    // /proc/1/root is only accessible to root; create_dir_all will
+    // return EACCES for any unprivileged user, which is exactly the
+    // failure mode we want to exercise.
+    cfg.storage.model_dir = "/proc/1/root".to_string();
+    (tmp, cfg)
+}
+
+// ── 1. Failure path: threshold > 0 + unwritable model_dir ─────────────────
+
+#[test]
+fn open_with_config_nli_fails_when_model_dir_unwritable_and_threshold_positive() {
+    let (_tmp, mut cfg) = config_with_unwritable_model_dir();
+    cfg.rag.nli_threshold = 0.5; // gate enabled → OnnxNliVerifier::new runs
+
+    let result = kebab_app::App::open_with_config(cfg);
+
+    let Err(err) = result else {
+        panic!(
+            "App::open_with_config must fail when model_dir is unwritable and nli_threshold > 0"
+        );
+    };
+    // The error chain must identify the OnnxNliVerifier as the source so
+    // an operator reading logs can trace the failure to the NLI config.
+    let err_chain = format!("{err:?}");
+    assert!(
+        err_chain.contains("OnnxNliVerifier"),
+        "error chain must mention OnnxNliVerifier; full chain: {err_chain}"
+    );
+}
+
+// ── 2. Success path: threshold = 0.0 → NLI verifier never constructed ──────
+
+#[test]
+fn open_with_config_nli_skipped_when_threshold_zero() {
+    let (_tmp, cfg) = config_with_unwritable_model_dir();
+    // Default nli_threshold is 0.0 — gate disabled, verifier skipped.
+    assert!(
+        (cfg.rag.nli_threshold - 0.0).abs() < f32::EPSILON,
+        "precondition: default nli_threshold must be 0.0 (gate disabled)"
+    );
+
+    // A bad model_dir must NOT cause a failure when the NLI gate is off.
+    let result = kebab_app::App::open_with_config(cfg);
+    assert!(
+        result.is_ok(),
+        "App::open_with_config must succeed when nli_threshold = 0.0 \
+         (OnnxNliVerifier is never constructed); err: {:?}",
+        result.err()
+    );
+}

crates/kebab-app/tests/search_korean.rs

@@ -46,3 +46,88 @@ fn korean_lexical_query_returns_korean_document() {
         hits.iter().map(|h| &h.doc_path.0).collect::<Vec<_>>()
     );
 }
+
+/// A4 Step 1c — multi-token Korean query (`해시 충돌`) must hit when
+/// the lexical builder routes it through a whole-phrase MATCH candidate.
+///
+/// Expected: FAIL until A5 (`build_match_string` redesign) lands — the
+/// current builder emits `"해시" "충돌"` AND, but FTS5 trigram tokenizer
+/// has no 2-char terms so each side is 0-hit. A5 introduces a whole-
+/// phrase candidate (`"해시 충돌"`) OR'd with the token AND, restoring
+/// hits for the dominant Korean usage pattern.
+#[test]
+fn lexical_multi_token_korean_query_hits() {
+    let env = TestEnv::lexical_only();
+
+    // Copy the synthetic Korean fixture (introduced in A4 Step 0) into
+    // the test workspace. The fixture contains the exact phrase
+    // "해시 충돌" multiple times.
+    let dest = env.workspace_root.join("hash-table.md");
+    let src = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"))
+        .join("..")
+        .join("..")
+        .join("fixtures")
+        .join("search")
+        .join("korean")
+        .join("hash-table.md");
+    std::fs::copy(&src, &dest).expect("copy korean fixture");
+
+    kebab_app::ingest_with_config(env.config.clone(), env.scope(), true)
+        .expect("ingest must succeed");
+
+    let hits = kebab_app::search_with_config(
+        env.config.clone(),
+        common::lexical_query("해시 충돌"),
+    )
+    .expect("search must succeed");
+
+    assert!(
+        !hits.is_empty(),
+        "multi-token Korean query '해시 충돌' must hit the hash-table fixture; got {:?}",
+        hits.iter().map(|h| &h.doc_path.0).collect::<Vec<_>>()
+    );
+    let any_hash_table = hits.iter().any(|h| h.doc_path.0.contains("hash-table"));
+    assert!(
+        any_hash_table,
+        "expected at least one hit on the hash-table fixture, got: {:?}",
+        hits.iter().map(|h| &h.doc_path.0).collect::<Vec<_>>()
+    );
+}
+
+/// A4 Step 1c — mixed Korean+English multi-token query (`Rust 충돌은`).
+/// Both tokens are ≥3 chars, so the redesigned builder (A5) emits
+/// `("Rust 충돌은") OR ("Rust" AND "충돌은")`. With trigram tokenizer
+/// each side has substring coverage in the document, so the AND branch
+/// alone is enough. Expected: FAIL pre-A5, PASS post-A5.
+#[test]
+fn lexical_mixed_korean_english_multi_token_query_hits() {
+    let env = TestEnv::lexical_only();
+    let doc_path = env.workspace_root.join("rust-hash.md");
+    std::fs::write(
+        &doc_path,
+        "# Rust 해시 테이블\n\nRust 의 std::collections::HashMap 에서 \
+         해시 충돌은 SipHash 로 완화한다.\n",
+    )
+    .expect("write rust-hash fixture");
+
+    kebab_app::ingest_with_config(env.config.clone(), env.scope(), true)
+        .expect("ingest must succeed");
+
+    let hits = kebab_app::search_with_config(
+        env.config.clone(),
+        common::lexical_query("Rust 충돌은"),
+    )
+    .expect("search must succeed");
+
+    assert!(
+        !hits.is_empty(),
+        "mixed Korean+English multi-token query 'Rust 충돌은' must hit the rust-hash fixture; got {:?}",
+        hits.iter().map(|h| &h.doc_path.0).collect::<Vec<_>>()
+    );
+    let any_rust_hash = hits.iter().any(|h| h.doc_path.0.contains("rust-hash"));
+    assert!(
+        any_rust_hash,
+        "expected at least one hit on the rust-hash fixture, got: {:?}",
+        hits.iter().map(|h| &h.doc_path.0).collect::<Vec<_>>()
+    );
+}

crates/kebab-app/tests/search_vector.rs

@@ -14,12 +14,10 @@ use common::TestEnv;
 fn require_avx_or_panic() {
     #[cfg(target_arch = "x86_64")]
     {
-        if !std::is_x86_feature_detected!("avx") {
-            panic!(
-                "kb-app vector integration test requires AVX-capable hardware; \
-                 host CPU lacks AVX. Run on an AVX-capable machine."
-            );
-        }
+        assert!(std::is_x86_feature_detected!("avx"), 
+            "kb-app vector integration test requires AVX-capable hardware; \
+             host CPU lacks AVX. Run on an AVX-capable machine."
+        );
     }
 }
 

crates/kebab-chunk/Cargo.toml

@@ -16,12 +16,16 @@ tracing                    = { workspace = true }
 serde_yaml                 = { workspace = true }
 
 [dev-dependencies]
-# kb-parse-md / kb-normalize are dev-only — used by the snapshot integration
-# test to build a CanonicalDocument from a fixture Markdown file. Forbidden as
-# regular deps per design §8 (chunker consumes CanonicalDocument from kb-core
-# only); `cargo tree -p kb-chunk --depth 1` (default scope, excludes dev-deps)
-# confirms this.
-kebab-parse-md = { path = "../kebab-parse-md" }
-kebab-normalize = { path = "../kebab-normalize" }
-serde_json      = { workspace = true }
-time            = { workspace = true }
+# kb-parse-md / kb-normalize / kb-parse-code are dev-only — used by the
+# snapshot integration tests to build a CanonicalDocument from fixture files.
+# Forbidden as regular deps per design §8 (chunker consumes CanonicalDocument
+# from kb-core only); `cargo tree -p kb-chunk --depth 1` (default scope,
+# excludes dev-deps) confirms this.
+kebab-parse-md   = { path = "../kebab-parse-md" }
+kebab-parse-code = { path = "../kebab-parse-code" }
+kebab-normalize  = { path = "../kebab-normalize" }
+serde_json       = { workspace = true }
+time             = { workspace = true }
+
+[lints]
+workspace = true

crates/kebab-chunk/src/code_c_ast_v1.rs

@@ -0,0 +1,322 @@
+//! `code-c-ast-v1` — maps a tree-sitter-derived C AST
+//! `CanonicalDocument` (one `Block::Code` per semantic unit, each with
+//! `SourceSpan::Code`) to chunks 1:1. A unit longer than
+//! `AST_CHUNK_MAX_LINES` is split into `<symbol> [part i/N]` sub-chunks
+//! at blank-line paragraph boundaries (design §9.1 oversize fallback).
+//!
+//! tree-sitter is intentionally NOT a dependency here: AST work is
+//! parser-side (`kebab-parse-code`, design §6.3). This chunker only
+//! consumes the `CanonicalDocument`.
+//!
+//! `AST_CHUNK_MAX_LINES` is a constant matching
+//! `IngestCodeCfg::default().ast_chunk_max_lines` (200). Per-medium
+//! config threading needs a chunker registry (P+); same deviation
+//! pattern as `pdf-page-v1`'s pinned `chunker_version`
+//! (`tasks/HOTFIXES.md`).
+
+use kebab_core::{
+    Block, BlockId, CanonicalDocument, Chunk, ChunkPolicy, Chunker, ChunkerVersion, DocumentId,
+    SourceSpan, id_for_chunk,
+};
+
+const VERSION_LABEL: &str = "code-c-ast-v1";
+const BYTES_PER_TOKEN: usize = 3;
+const POLICY_HASH_HEX_LEN: usize = 16;
+const AST_CHUNK_MAX_LINES: u32 = 200;
+
+#[derive(Clone, Copy, Debug, Default)]
+pub struct CodeCAstV1Chunker;
+
+impl Chunker for CodeCAstV1Chunker {
+    fn chunker_version(&self) -> ChunkerVersion {
+        ChunkerVersion(VERSION_LABEL.to_string())
+    }
+
+    fn policy_hash(&self, policy: &ChunkPolicy) -> String {
+        let bytes = serde_json_canonicalizer::to_vec(policy)
+            .expect("canonical JSON serialization of ChunkPolicy must not fail");
+        let hex = blake3::hash(&bytes).to_hex().to_string();
+        hex[..POLICY_HASH_HEX_LEN].to_string()
+    }
+
+    fn chunk(
+        &self,
+        doc: &CanonicalDocument,
+        policy: &ChunkPolicy,
+    ) -> anyhow::Result<Vec<Chunk>> {
+        for b in &doc.blocks {
+            let c = match b {
+                Block::Code(c) => c,
+                _ => anyhow::bail!(
+                    "CodeCAstV1Chunker only handles code docs (got non-Code block)"
+                ),
+            };
+            if !matches!(c.common.source_span, SourceSpan::Code { .. }) {
+                anyhow::bail!(
+                    "CodeCAstV1Chunker only handles code docs (got non-Code source_span)"
+                );
+            }
+        }
+
+        let base_policy_hash = self.policy_hash(policy);
+        let chunker_version = self.chunker_version();
+        let mut out: Vec<Chunk> = Vec::new();
+
+        for b in &doc.blocks {
+            let cb = match b {
+                Block::Code(c) => c,
+                _ => unreachable!("validated above"),
+            };
+            let (ls, le, symbol, lang) = match &cb.common.source_span {
+                SourceSpan::Code { line_start, line_end, symbol, lang } => {
+                    (*line_start, *line_end, symbol.clone(), lang.clone())
+                }
+                _ => unreachable!("validated above"),
+            };
+            let block_ids: Vec<BlockId> = vec![cb.common.block_id.clone()];
+            let span_lines = le.saturating_sub(ls) + 1;
+
+            if span_lines <= AST_CHUNK_MAX_LINES {
+                let span = SourceSpan::Code {
+                    line_start: ls,
+                    line_end: le,
+                    symbol: symbol.clone(),
+                    lang: lang.clone(),
+                };
+                out.push(make_chunk(
+                    doc, &chunker_version, &block_ids, &base_policy_hash,
+                    None, span, cb.code.clone(),
+                ));
+            } else {
+                let parts = split_oversize(&cb.code);
+                let n = parts.len();
+                for (i, (off_start, off_end, text)) in parts.into_iter().enumerate() {
+                    let part_ls = ls + off_start;
+                    let part_le = ls + off_end;
+                    let part_sym = symbol
+                        .as_ref()
+                        .map(|s| format!("{s} [part {}/{n}]", i + 1));
+                    let span = SourceSpan::Code {
+                        line_start: part_ls,
+                        line_end: part_le,
+                        symbol: part_sym,
+                        lang: lang.clone(),
+                    };
+                    out.push(make_chunk(
+                        doc, &chunker_version, &block_ids, &base_policy_hash,
+                        Some(part_ls), span, text,
+                    ));
+                }
+            }
+        }
+
+        tracing::debug!(
+            target: "kebab-chunk",
+            doc_id = %doc.doc_id,
+            chunks = out.len(),
+            "code-c-ast-v1 chunked",
+        );
+        Ok(out)
+    }
+}
+
+#[allow(clippy::too_many_arguments)]
+fn make_chunk(
+    doc: &CanonicalDocument,
+    chunker_version: &ChunkerVersion,
+    block_ids: &[BlockId],
+    base_policy_hash: &str,
+    split_key: Option<u32>,
+    span: SourceSpan,
+    text: String,
+) -> Chunk {
+    let id_hash = match split_key {
+        Some(k) => format!("{base_policy_hash}#L{k}"),
+        None => base_policy_hash.to_string(),
+    };
+    let chunk_id = id_for_chunk(&doc.doc_id, chunker_version, block_ids, &id_hash);
+    let token_estimate = text.len().div_ceil(BYTES_PER_TOKEN);
+    Chunk {
+        chunk_id,
+        doc_id: DocumentId(doc.doc_id.0.clone()),
+        block_ids: block_ids.to_vec(),
+        text,
+        heading_path: Vec::new(),
+        source_spans: vec![span],
+        token_estimate,
+        chunker_version: chunker_version.clone(),
+        policy_hash: base_policy_hash.to_string(),
+    }
+}
+
+/// Split an oversize unit at blank-line paragraph boundaries, greedily
+/// gluing paragraphs until ~`AST_CHUNK_MAX_LINES` lines accumulate.
+/// Returns `(line_offset_start, line_offset_end, text)` where offsets are
+/// 0-based within the unit (caller adds the unit's absolute `line_start`).
+fn split_oversize(code: &str) -> Vec<(u32, u32, String)> {
+    let lines: Vec<&str> = code.split('\n').collect();
+    let total = lines.len() as u32;
+    let mut out: Vec<(u32, u32, String)> = Vec::new();
+    let mut start: u32 = 0;
+    while start < total {
+        let mut end = (start + AST_CHUNK_MAX_LINES).min(total);
+        let floor = start + (AST_CHUNK_MAX_LINES * 4 / 5);
+        if end < total {
+            if let Some(b) = (floor.min(end)..end)
+                .rev()
+                .find(|&i| lines[i as usize].trim().is_empty())
+            {
+                end = b + 1;
+            }
+        }
+        let text = lines[start as usize..end as usize].join("\n");
+        out.push((start, end.saturating_sub(1), text));
+        start = end;
+    }
+    if out.is_empty() {
+        out.push((0, total.saturating_sub(1), code.to_string()));
+    }
+    out
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use kebab_core::{
+        Block, CanonicalDocument, ChunkPolicy, Chunker, ChunkerVersion, CodeBlock, CommonBlock,
+        SourceSpan, id_for_block, id_for_doc, AssetId, Lang, Metadata, ParserVersion, Provenance,
+        SourceType, TrustLevel, WorkspacePath,
+    };
+    use time::OffsetDateTime;
+
+    fn code_doc(units: &[(&str, u32, u32, &str)]) -> CanonicalDocument {
+        let wp = WorkspacePath("crates/x/src/a.c".into());
+        let aid = AssetId("a".repeat(64));
+        let pv = ParserVersion("code-c-v1".into());
+        let doc_id = id_for_doc(&wp, &aid, &pv);
+        let blocks = units
+            .iter()
+            .enumerate()
+            .map(|(i, (sym, ls, le, code))| {
+                let span = SourceSpan::Code {
+                    line_start: *ls,
+                    line_end: *le,
+                    symbol: Some((*sym).to_string()),
+                    lang: Some("c".into()),
+                };
+                let bid = id_for_block(&doc_id, "code", &[], i as u32, &span);
+                Block::Code(CodeBlock {
+                    common: CommonBlock { block_id: bid, heading_path: vec![], source_span: span },
+                    lang: Some("c".into()),
+                    code: (*code).to_string(),
+                })
+            })
+            .collect();
+        CanonicalDocument {
+            doc_id, source_asset_id: aid, workspace_path: wp, title: "a".into(),
+            lang: Lang("und".into()), blocks,
+            metadata: Metadata {
+                aliases: vec![], tags: vec![],
+                created_at: OffsetDateTime::from_unix_timestamp(1_700_000_000).unwrap(),
+                updated_at: OffsetDateTime::from_unix_timestamp(1_700_000_000).unwrap(),
+                source_type: SourceType::Note, trust_level: TrustLevel::Primary,
+                user_id_alias: None, user: Default::default(),
+                repo: Some("kebab".into()), git_branch: Some("main".into()),
+                git_commit: Some("0".repeat(40)), code_lang: Some("c".into()),
+            },
+            provenance: Provenance { events: vec![] },
+            parser_version: pv, schema_version: 1, doc_version: 1,
+            last_chunker_version: None, last_embedding_version: None,
+        }
+    }
+    fn policy() -> ChunkPolicy {
+        ChunkPolicy { target_tokens: 500, overlap_tokens: 80,
+            respect_markdown_headings: false,
+            chunker_version: ChunkerVersion(VERSION_LABEL.into()) }
+    }
+
+    #[test]
+    fn chunker_version_is_code_c_ast_v1() {
+        assert_eq!(CodeCAstV1Chunker.chunker_version(),
+            ChunkerVersion("code-c-ast-v1".into()));
+    }
+
+    #[test]
+    fn one_chunk_per_unit_preserves_code_span() {
+        let doc = code_doc(&[
+            ("parse", 1, 3, "int parse() {\n\t// x\n}"),
+            ("print", 5, 7, "void print() {\n\t//\n\treturn;\n}"),
+        ]);
+        let chunks = CodeCAstV1Chunker.chunk(&doc, &policy()).unwrap();
+        assert_eq!(chunks.len(), 2);
+        for c in &chunks {
+            assert_eq!(c.source_spans.len(), 1);
+            assert!(matches!(c.source_spans[0], SourceSpan::Code { .. }));
+            assert_eq!(c.heading_path, Vec::<String>::new());
+            assert_eq!(c.chunker_version.0, "code-c-ast-v1");
+        }
+        match &chunks[0].source_spans[0] {
+            SourceSpan::Code { symbol, line_start, line_end, .. } => {
+                assert_eq!(symbol.as_deref(), Some("parse"));
+                assert_eq!((*line_start, *line_end), (1, 3));
+            }
+            _ => unreachable!(),
+        }
+    }
+
+    #[test]
+    fn oversize_unit_splits_into_parts_with_unique_ids() {
+        let body = (0..500).map(|i| format!("\tx{i} = {i};\n")).collect::<String>();
+        let code = format!("int big() {{\n{body}\n}}");
+        let doc = code_doc(&[("big", 1, 502, &code)]);
+        let chunks = CodeCAstV1Chunker.chunk(&doc, &policy()).unwrap();
+        assert!(chunks.len() >= 2, "oversize unit must split, got {}", chunks.len());
+        for c in &chunks {
+            match &c.source_spans[0] {
+                SourceSpan::Code { symbol, .. } => {
+                    assert!(symbol.as_deref().unwrap().starts_with("big [part "),
+                        "part-numbered symbol, got {symbol:?}");
+                }
+                _ => unreachable!(),
+            }
+        }
+        let mut ids: Vec<&str> = chunks.iter().map(|c| c.chunk_id.0.as_str()).collect();
+        let n = ids.len(); ids.sort_unstable(); ids.dedup();
+        assert_eq!(ids.len(), n, "chunk_ids unique across split parts");
+    }
+
+    #[test]
+    fn non_code_doc_errors() {
+        use kebab_core::TextBlock;
+        let mut doc = code_doc(&[("parse", 1, 1, "int parse() {}")]);
+        doc.blocks = vec![Block::Paragraph(TextBlock {
+            common: CommonBlock {
+                block_id: kebab_core::BlockId("b".into()),
+                heading_path: vec![],
+                source_span: SourceSpan::Line { start: 1, end: 1 },
+            },
+            text: "x".into(), inlines: vec![],
+        })];
+        let err = CodeCAstV1Chunker.chunk(&doc, &policy()).unwrap_err();
+        assert!(err.to_string().contains("CodeCAstV1Chunker"));
+    }
+
+    #[test]
+    fn deterministic_chunk_ids_1000() {
+        let doc = code_doc(&[("parse", 1, 2, "int parse() {}\n")]);
+        let base: Vec<String> = CodeCAstV1Chunker.chunk(&doc, &policy())
+            .unwrap().into_iter().map(|c| c.chunk_id.0).collect();
+        for _ in 0..1000 {
+            let again: Vec<String> = CodeCAstV1Chunker.chunk(&doc, &policy())
+                .unwrap().into_iter().map(|c| c.chunk_id.0).collect();
+            assert_eq!(again, base);
+        }
+    }
+
+    #[test]
+    fn policy_hash_matches_md_heading_v1() {
+        let p = policy();
+        assert_eq!(CodeCAstV1Chunker.policy_hash(&p),
+            crate::MdHeadingV1Chunker.policy_hash(&p));
+    }
+}

crates/kebab-chunk/src/code_cpp_ast_v1.rs

@@ -0,0 +1,322 @@
+//! `code-cpp-ast-v1` — maps a tree-sitter-derived C++ AST
+//! `CanonicalDocument` (one `Block::Code` per semantic unit, each with
+//! `SourceSpan::Code`) to chunks 1:1. A unit longer than
+//! `AST_CHUNK_MAX_LINES` is split into `<symbol> [part i/N]` sub-chunks
+//! at blank-line paragraph boundaries (design §9.1 oversize fallback).
+//!
+//! tree-sitter is intentionally NOT a dependency here: AST work is
+//! parser-side (`kebab-parse-code`, design §6.3). This chunker only
+//! consumes the `CanonicalDocument`.
+//!
+//! `AST_CHUNK_MAX_LINES` is a constant matching
+//! `IngestCodeCfg::default().ast_chunk_max_lines` (200). Per-medium
+//! config threading needs a chunker registry (P+); same deviation
+//! pattern as `pdf-page-v1`'s pinned `chunker_version`
+//! (`tasks/HOTFIXES.md`).
+
+use kebab_core::{
+    Block, BlockId, CanonicalDocument, Chunk, ChunkPolicy, Chunker, ChunkerVersion, DocumentId,
+    SourceSpan, id_for_chunk,
+};
+
+const VERSION_LABEL: &str = "code-cpp-ast-v1";
+const BYTES_PER_TOKEN: usize = 3;
+const POLICY_HASH_HEX_LEN: usize = 16;
+const AST_CHUNK_MAX_LINES: u32 = 200;
+
+#[derive(Clone, Copy, Debug, Default)]
+pub struct CodeCppAstV1Chunker;
+
+impl Chunker for CodeCppAstV1Chunker {
+    fn chunker_version(&self) -> ChunkerVersion {
+        ChunkerVersion(VERSION_LABEL.to_string())
+    }
+
+    fn policy_hash(&self, policy: &ChunkPolicy) -> String {
+        let bytes = serde_json_canonicalizer::to_vec(policy)
+            .expect("canonical JSON serialization of ChunkPolicy must not fail");
+        let hex = blake3::hash(&bytes).to_hex().to_string();
+        hex[..POLICY_HASH_HEX_LEN].to_string()
+    }
+
+    fn chunk(
+        &self,
+        doc: &CanonicalDocument,
+        policy: &ChunkPolicy,
+    ) -> anyhow::Result<Vec<Chunk>> {
+        for b in &doc.blocks {
+            let c = match b {
+                Block::Code(c) => c,
+                _ => anyhow::bail!(
+                    "CodeCppAstV1Chunker only handles code docs (got non-Code block)"
+                ),
+            };
+            if !matches!(c.common.source_span, SourceSpan::Code { .. }) {
+                anyhow::bail!(
+                    "CodeCppAstV1Chunker only handles code docs (got non-Code source_span)"
+                );
+            }
+        }
+
+        let base_policy_hash = self.policy_hash(policy);
+        let chunker_version = self.chunker_version();
+        let mut out: Vec<Chunk> = Vec::new();
+
+        for b in &doc.blocks {
+            let cb = match b {
+                Block::Code(c) => c,
+                _ => unreachable!("validated above"),
+            };
+            let (ls, le, symbol, lang) = match &cb.common.source_span {
+                SourceSpan::Code { line_start, line_end, symbol, lang } => {
+                    (*line_start, *line_end, symbol.clone(), lang.clone())
+                }
+                _ => unreachable!("validated above"),
+            };
+            let block_ids: Vec<BlockId> = vec![cb.common.block_id.clone()];
+            let span_lines = le.saturating_sub(ls) + 1;
+
+            if span_lines <= AST_CHUNK_MAX_LINES {
+                let span = SourceSpan::Code {
+                    line_start: ls,
+                    line_end: le,
+                    symbol: symbol.clone(),
+                    lang: lang.clone(),
+                };
+                out.push(make_chunk(
+                    doc, &chunker_version, &block_ids, &base_policy_hash,
+                    None, span, cb.code.clone(),
+                ));
+            } else {
+                let parts = split_oversize(&cb.code);
+                let n = parts.len();
+                for (i, (off_start, off_end, text)) in parts.into_iter().enumerate() {
+                    let part_ls = ls + off_start;
+                    let part_le = ls + off_end;
+                    let part_sym = symbol
+                        .as_ref()
+                        .map(|s| format!("{s} [part {}/{n}]", i + 1));
+                    let span = SourceSpan::Code {
+                        line_start: part_ls,
+                        line_end: part_le,
+                        symbol: part_sym,
+                        lang: lang.clone(),
+                    };
+                    out.push(make_chunk(
+                        doc, &chunker_version, &block_ids, &base_policy_hash,
+                        Some(part_ls), span, text,
+                    ));
+                }
+            }
+        }
+
+        tracing::debug!(
+            target: "kebab-chunk",
+            doc_id = %doc.doc_id,
+            chunks = out.len(),
+            "code-cpp-ast-v1 chunked",
+        );
+        Ok(out)
+    }
+}
+
+#[allow(clippy::too_many_arguments)]
+fn make_chunk(
+    doc: &CanonicalDocument,
+    chunker_version: &ChunkerVersion,
+    block_ids: &[BlockId],
+    base_policy_hash: &str,
+    split_key: Option<u32>,
+    span: SourceSpan,
+    text: String,
+) -> Chunk {
+    let id_hash = match split_key {
+        Some(k) => format!("{base_policy_hash}#L{k}"),
+        None => base_policy_hash.to_string(),
+    };
+    let chunk_id = id_for_chunk(&doc.doc_id, chunker_version, block_ids, &id_hash);
+    let token_estimate = text.len().div_ceil(BYTES_PER_TOKEN);
+    Chunk {
+        chunk_id,
+        doc_id: DocumentId(doc.doc_id.0.clone()),
+        block_ids: block_ids.to_vec(),
+        text,
+        heading_path: Vec::new(),
+        source_spans: vec![span],
+        token_estimate,
+        chunker_version: chunker_version.clone(),
+        policy_hash: base_policy_hash.to_string(),
+    }
+}
+
+/// Split an oversize unit at blank-line paragraph boundaries, greedily
+/// gluing paragraphs until ~`AST_CHUNK_MAX_LINES` lines accumulate.
+/// Returns `(line_offset_start, line_offset_end, text)` where offsets are
+/// 0-based within the unit (caller adds the unit's absolute `line_start`).
+fn split_oversize(code: &str) -> Vec<(u32, u32, String)> {
+    let lines: Vec<&str> = code.split('\n').collect();
+    let total = lines.len() as u32;
+    let mut out: Vec<(u32, u32, String)> = Vec::new();
+    let mut start: u32 = 0;
+    while start < total {
+        let mut end = (start + AST_CHUNK_MAX_LINES).min(total);
+        let floor = start + (AST_CHUNK_MAX_LINES * 4 / 5);
+        if end < total {
+            if let Some(b) = (floor.min(end)..end)
+                .rev()
+                .find(|&i| lines[i as usize].trim().is_empty())
+            {
+                end = b + 1;
+            }
+        }
+        let text = lines[start as usize..end as usize].join("\n");
+        out.push((start, end.saturating_sub(1), text));
+        start = end;
+    }
+    if out.is_empty() {
+        out.push((0, total.saturating_sub(1), code.to_string()));
+    }
+    out
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use kebab_core::{
+        Block, CanonicalDocument, ChunkPolicy, Chunker, ChunkerVersion, CodeBlock, CommonBlock,
+        SourceSpan, id_for_block, id_for_doc, AssetId, Lang, Metadata, ParserVersion, Provenance,
+        SourceType, TrustLevel, WorkspacePath,
+    };
+    use time::OffsetDateTime;
+
+    fn code_doc(units: &[(&str, u32, u32, &str)]) -> CanonicalDocument {
+        let wp = WorkspacePath("crates/x/src/a.cpp".into());
+        let aid = AssetId("a".repeat(64));
+        let pv = ParserVersion("code-cpp-v1".into());
+        let doc_id = id_for_doc(&wp, &aid, &pv);
+        let blocks = units
+            .iter()
+            .enumerate()
+            .map(|(i, (sym, ls, le, code))| {
+                let span = SourceSpan::Code {
+                    line_start: *ls,
+                    line_end: *le,
+                    symbol: Some((*sym).to_string()),
+                    lang: Some("cpp".into()),
+                };
+                let bid = id_for_block(&doc_id, "code", &[], i as u32, &span);
+                Block::Code(CodeBlock {
+                    common: CommonBlock { block_id: bid, heading_path: vec![], source_span: span },
+                    lang: Some("cpp".into()),
+                    code: (*code).to_string(),
+                })
+            })
+            .collect();
+        CanonicalDocument {
+            doc_id, source_asset_id: aid, workspace_path: wp, title: "a".into(),
+            lang: Lang("und".into()), blocks,
+            metadata: Metadata {
+                aliases: vec![], tags: vec![],
+                created_at: OffsetDateTime::from_unix_timestamp(1_700_000_000).unwrap(),
+                updated_at: OffsetDateTime::from_unix_timestamp(1_700_000_000).unwrap(),
+                source_type: SourceType::Note, trust_level: TrustLevel::Primary,
+                user_id_alias: None, user: Default::default(),
+                repo: Some("kebab".into()), git_branch: Some("main".into()),
+                git_commit: Some("0".repeat(40)), code_lang: Some("cpp".into()),
+            },
+            provenance: Provenance { events: vec![] },
+            parser_version: pv, schema_version: 1, doc_version: 1,
+            last_chunker_version: None, last_embedding_version: None,
+        }
+    }
+    fn policy() -> ChunkPolicy {
+        ChunkPolicy { target_tokens: 500, overlap_tokens: 80,
+            respect_markdown_headings: false,
+            chunker_version: ChunkerVersion(VERSION_LABEL.into()) }
+    }
+
+    #[test]
+    fn chunker_version_is_code_cpp_ast_v1() {
+        assert_eq!(CodeCppAstV1Chunker.chunker_version(),
+            ChunkerVersion("code-cpp-ast-v1".into()));
+    }
+
+    #[test]
+    fn one_chunk_per_unit_preserves_code_span() {
+        let doc = code_doc(&[
+            ("parse", 1, 3, "int parse() {\n\t// x\n}"),
+            ("print", 5, 7, "void print() {\n\t//\n\treturn;\n}"),
+        ]);
+        let chunks = CodeCppAstV1Chunker.chunk(&doc, &policy()).unwrap();
+        assert_eq!(chunks.len(), 2);
+        for c in &chunks {
+            assert_eq!(c.source_spans.len(), 1);
+            assert!(matches!(c.source_spans[0], SourceSpan::Code { .. }));
+            assert_eq!(c.heading_path, Vec::<String>::new());
+            assert_eq!(c.chunker_version.0, "code-cpp-ast-v1");
+        }
+        match &chunks[0].source_spans[0] {
+            SourceSpan::Code { symbol, line_start, line_end, .. } => {
+                assert_eq!(symbol.as_deref(), Some("parse"));
+                assert_eq!((*line_start, *line_end), (1, 3));
+            }
+            _ => unreachable!(),
+        }
+    }
+
+    #[test]
+    fn oversize_unit_splits_into_parts_with_unique_ids() {
+        let body = (0..500).map(|i| format!("\tx{i} = {i};\n")).collect::<String>();
+        let code = format!("int big() {{\n{body}\n}}");
+        let doc = code_doc(&[("big", 1, 502, &code)]);
+        let chunks = CodeCppAstV1Chunker.chunk(&doc, &policy()).unwrap();
+        assert!(chunks.len() >= 2, "oversize unit must split, got {}", chunks.len());
+        for c in &chunks {
+            match &c.source_spans[0] {
+                SourceSpan::Code { symbol, .. } => {
+                    assert!(symbol.as_deref().unwrap().starts_with("big [part "),
+                        "part-numbered symbol, got {symbol:?}");
+                }
+                _ => unreachable!(),
+            }
+        }
+        let mut ids: Vec<&str> = chunks.iter().map(|c| c.chunk_id.0.as_str()).collect();
+        let n = ids.len(); ids.sort_unstable(); ids.dedup();
+        assert_eq!(ids.len(), n, "chunk_ids unique across split parts");
+    }
+
+    #[test]
+    fn non_code_doc_errors() {
+        use kebab_core::TextBlock;
+        let mut doc = code_doc(&[("parse", 1, 1, "int parse() {}")]);
+        doc.blocks = vec![Block::Paragraph(TextBlock {
+            common: CommonBlock {
+                block_id: kebab_core::BlockId("b".into()),
+                heading_path: vec![],
+                source_span: SourceSpan::Line { start: 1, end: 1 },
+            },
+            text: "x".into(), inlines: vec![],
+        })];
+        let err = CodeCppAstV1Chunker.chunk(&doc, &policy()).unwrap_err();
+        assert!(err.to_string().contains("CodeCppAstV1Chunker"));
+    }
+
+    #[test]
+    fn deterministic_chunk_ids_1000() {
+        let doc = code_doc(&[("parse", 1, 2, "int parse() {}\n")]);
+        let base: Vec<String> = CodeCppAstV1Chunker.chunk(&doc, &policy())
+            .unwrap().into_iter().map(|c| c.chunk_id.0).collect();
+        for _ in 0..1000 {
+            let again: Vec<String> = CodeCppAstV1Chunker.chunk(&doc, &policy())
+                .unwrap().into_iter().map(|c| c.chunk_id.0).collect();
+            assert_eq!(again, base);
+        }
+    }
+
+    #[test]
+    fn policy_hash_matches_md_heading_v1() {
+        let p = policy();
+        assert_eq!(CodeCppAstV1Chunker.policy_hash(&p),
+            crate::MdHeadingV1Chunker.policy_hash(&p));
+    }
+}

crates/kebab-chunk/src/code_go_ast_v1.rs

@@ -281,7 +281,7 @@ mod tests {
             }
         }
         let mut ids: Vec<&str> = chunks.iter().map(|c| c.chunk_id.0.as_str()).collect();
-        let n = ids.len(); ids.sort(); ids.dedup();
+        let n = ids.len(); ids.sort_unstable(); ids.dedup();
         assert_eq!(ids.len(), n, "chunk_ids unique across split parts");
     }
 

crates/kebab-chunk/src/code_java_ast_v1.rs

@@ -281,7 +281,7 @@ mod tests {
             }
         }
         let mut ids: Vec<&str> = chunks.iter().map(|c| c.chunk_id.0.as_str()).collect();
-        let n = ids.len(); ids.sort(); ids.dedup();
+        let n = ids.len(); ids.sort_unstable(); ids.dedup();
         assert_eq!(ids.len(), n, "chunk_ids unique across split parts");
     }
 

crates/kebab-chunk/src/code_js_ast_v1.rs

@@ -281,7 +281,7 @@ mod tests {
             }
         }
         let mut ids: Vec<&str> = chunks.iter().map(|c| c.chunk_id.0.as_str()).collect();
-        let n = ids.len(); ids.sort(); ids.dedup();
+        let n = ids.len(); ids.sort_unstable(); ids.dedup();
         assert_eq!(ids.len(), n, "chunk_ids unique across split parts");
     }
 

crates/kebab-chunk/src/code_kotlin_ast_v1.rs

@@ -281,7 +281,7 @@ mod tests {
             }
         }
         let mut ids: Vec<&str> = chunks.iter().map(|c| c.chunk_id.0.as_str()).collect();
-        let n = ids.len(); ids.sort(); ids.dedup();
+        let n = ids.len(); ids.sort_unstable(); ids.dedup();
         assert_eq!(ids.len(), n, "chunk_ids unique across split parts");
     }
 

crates/kebab-chunk/src/code_python_ast_v1.rs

@@ -281,7 +281,7 @@ mod tests {
             }
         }
         let mut ids: Vec<&str> = chunks.iter().map(|c| c.chunk_id.0.as_str()).collect();
-        let n = ids.len(); ids.sort(); ids.dedup();
+        let n = ids.len(); ids.sort_unstable(); ids.dedup();
         assert_eq!(ids.len(), n, "chunk_ids unique across split parts");
     }
 

crates/kebab-chunk/src/code_rust_ast_v1.rs

@@ -281,7 +281,7 @@ mod tests {
             }
         }
         let mut ids: Vec<&str> = chunks.iter().map(|c| c.chunk_id.0.as_str()).collect();
-        let n = ids.len(); ids.sort(); ids.dedup();
+        let n = ids.len(); ids.sort_unstable(); ids.dedup();
         assert_eq!(ids.len(), n, "chunk_ids unique across split parts");
     }
 

crates/kebab-chunk/src/code_text_paragraph_v1.rs

@@ -0,0 +1,170 @@
+//! p10-3: Tier 3 paragraph + line-window fallback chunker.
+//!
+//! Splits code/text files on blank-line paragraph boundaries.  Paragraphs
+//! with more than 80 lines are further split into 80-line windows with a
+//! 20-line overlap (stride 60) — the same oversize pattern used by Tier 1/2
+//! chunkers but without AST structure, hence no symbol.
+//!
+//! Per spec §9.3: all emitted chunks carry `symbol: None`.
+
+use crate::tier2_shared::{build_chunk_no_symbol, policy_hash};
+use anyhow::Result;
+use kebab_core::{Block, CanonicalDocument, Chunk, ChunkPolicy, ChunkerVersion, Chunker};
+
+pub const VERSION_LABEL: &str = "code-text-paragraph-v1";
+
+/// Lines-per-window for the oversize fallback (Tier 3).
+const FALLBACK_LINES_PER_CHUNK: usize = 80;
+/// Overlap between consecutive windows.
+const FALLBACK_LINES_OVERLAP: usize = 20;
+// stride = FALLBACK_LINES_PER_CHUNK - FALLBACK_LINES_OVERLAP = 60.
+
+#[derive(Clone, Copy, Debug, Default)]
+pub struct CodeTextParagraphV1Chunker;
+
+impl Chunker for CodeTextParagraphV1Chunker {
+    fn chunker_version(&self) -> ChunkerVersion {
+        ChunkerVersion(VERSION_LABEL.to_string())
+    }
+
+    fn policy_hash(&self, policy: &ChunkPolicy) -> String {
+        policy_hash(policy)
+    }
+
+    fn chunk(&self, doc: &CanonicalDocument, policy: &ChunkPolicy) -> Result<Vec<Chunk>> {
+        // Expect a single Block::Code carrying the full source text.
+        let (text, lang_str) = match doc.blocks.first() {
+            Some(Block::Code(cb)) => (cb.code.as_str(), cb.lang.as_deref().unwrap_or("")),
+            _ => return Ok(vec![]),
+        };
+
+        let mut chunks = Vec::new();
+        for para in split_paragraphs(text) {
+            push_paragraph(&mut chunks, doc, policy, &para, lang_str)?;
+        }
+
+        tracing::debug!(
+            target: "kebab-chunk",
+            doc_id = %doc.doc_id,
+            chunks = chunks.len(),
+            "code-text-paragraph-v1 chunked",
+        );
+
+        Ok(chunks)
+    }
+}
+
+/// A contiguous run of non-blank lines from the source text.
+struct Paragraph {
+    /// Lines joined with `\n` (no trailing newline).
+    text: String,
+    /// 1-indexed line number of the first line in the source file.
+    line_start: u32,
+    /// 1-indexed line number of the last line in the source file.
+    line_end: u32,
+}
+
+/// Split `text` into `Paragraph`s separated by blank (all-whitespace) lines.
+///
+/// Blank lines are treated as boundaries and are NOT included in any
+/// paragraph's line range.  Paragraphs that would consist entirely of blank
+/// lines are skipped.
+fn split_paragraphs(text: &str) -> Vec<Paragraph> {
+    let mut paragraphs = Vec::new();
+    let mut current: Vec<&str> = Vec::new();
+    let mut current_start: Option<u32> = None;
+
+    for (idx, line) in text.lines().enumerate() {
+        let line_no = (idx + 1) as u32;
+        let is_blank = line.trim().is_empty();
+        if is_blank {
+            if let Some(start) = current_start.take() {
+                let end = start + current.len() as u32 - 1;
+                paragraphs.push(Paragraph {
+                    text: current.join("\n"),
+                    line_start: start,
+                    line_end: end,
+                });
+                current.clear();
+            }
+        } else {
+            if current_start.is_none() {
+                current_start = Some(line_no);
+            }
+            current.push(line);
+        }
+    }
+    // Flush any trailing paragraph not terminated by a blank line.
+    if let Some(start) = current_start {
+        let end = start + current.len() as u32 - 1;
+        paragraphs.push(Paragraph {
+            text: current.join("\n"),
+            line_start: start,
+            line_end: end,
+        });
+    }
+    paragraphs
+}
+
+/// Emit one or more chunks for a single paragraph.
+///
+/// Paragraphs with ≤ `FALLBACK_LINES_PER_CHUNK` lines become a single chunk.
+/// Larger paragraphs are split into overlapping windows of
+/// `FALLBACK_LINES_PER_CHUNK` lines with stride `FALLBACK_LINES_PER_CHUNK -
+/// FALLBACK_LINES_OVERLAP`.  The last window may be shorter.  Window starts
+/// are passed as `split_key` so `id_for_chunk` can produce distinct ids
+/// across windows.
+fn push_paragraph(
+    out: &mut Vec<Chunk>,
+    doc: &CanonicalDocument,
+    policy: &ChunkPolicy,
+    para: &Paragraph,
+    lang: &str,
+) -> Result<()> {
+    let n_lines = (para.line_end - para.line_start + 1) as usize;
+
+    if n_lines <= FALLBACK_LINES_PER_CHUNK {
+        // Use line_start as split_key so each paragraph gets a distinct
+        // chunk_id even when block_ids is empty (no symbol, no AST structure).
+        // Without this, all short paragraphs from the same doc share the same
+        // base_policy_hash and therefore the same id_for_chunk result.
+        out.push(build_chunk_no_symbol(
+            doc,
+            policy,
+            &para.text,
+            para.line_start,
+            para.line_end,
+            lang,
+            VERSION_LABEL,
+            Some(para.line_start),
+        ));
+        return Ok(());
+    }
+
+    // Oversize: line-window split with overlap.
+    let stride = FALLBACK_LINES_PER_CHUNK - FALLBACK_LINES_OVERLAP;
+    let lines: Vec<&str> = para.text.lines().collect();
+    let mut i = 0usize;
+    loop {
+        let end = (i + FALLBACK_LINES_PER_CHUNK).min(lines.len());
+        let window_text = lines[i..end].join("\n");
+        let window_start = para.line_start + i as u32;
+        let window_end = para.line_start + (end as u32) - 1;
+        // Use window_start as split_key so chunk_ids are unique across windows.
+        out.push(build_chunk_no_symbol(
+            doc,
+            policy,
+            &window_text,
+            window_start,
+            window_end,
+            lang,
+            VERSION_LABEL,
+            Some(window_start),
+        ));
+        if end == lines.len() {
+            break;
+        }
+        i += stride;
+    }
+    Ok(())
+}

crates/kebab-chunk/src/code_ts_ast_v1.rs

@@ -281,7 +281,7 @@ mod tests {
             }
         }
         let mut ids: Vec<&str> = chunks.iter().map(|c| c.chunk_id.0.as_str()).collect();
-        let n = ids.len(); ids.sort(); ids.dedup();
+        let n = ids.len(); ids.sort_unstable(); ids.dedup();
         assert_eq!(ids.len(), n, "chunk_ids unique across split parts");
     }
 

crates/kebab-chunk/src/dockerfile_file_v1.rs

@@ -43,6 +43,7 @@ impl Chunker for DockerfileFileV1Chunker {
             "<dockerfile>",
             "dockerfile",
             VERSION_LABEL,
+            None,
         )?;
 
         tracing::debug!(

crates/kebab-chunk/src/k8s_manifest_resource_v1.rs

@@ -85,6 +85,7 @@ impl Chunker for K8sManifestResourceV1Chunker {
                 &symbol,
                 "yaml",
                 VERSION_LABEL,
+                Some(slice.line_start),
             )?;
         }
 

crates/kebab-chunk/src/lib.rs

@@ -15,6 +15,8 @@
 //! embedder, the retriever, the LLM, the RAG layer, or the UI layers.
 //! It consumes `CanonicalDocument` purely through `kb-core` types.
 
+mod code_c_ast_v1;
+mod code_cpp_ast_v1;
 mod code_go_ast_v1;
 mod code_java_ast_v1;
 mod code_js_ast_v1;
@@ -28,7 +30,10 @@ mod tier2_shared;
 pub mod k8s_manifest_resource_v1;
 pub mod dockerfile_file_v1;
 pub mod manifest_file_v1;
+pub mod code_text_paragraph_v1;
 
+pub use code_c_ast_v1::CodeCAstV1Chunker;
+pub use code_cpp_ast_v1::CodeCppAstV1Chunker;
 pub use code_go_ast_v1::CodeGoAstV1Chunker;
 pub use code_java_ast_v1::CodeJavaAstV1Chunker;
 pub use code_js_ast_v1::CodeJsAstV1Chunker;
@@ -41,3 +46,4 @@ pub use pdf_page_v1::PdfPageV1Chunker;
 pub use k8s_manifest_resource_v1::K8sManifestResourceV1Chunker;
 pub use dockerfile_file_v1::DockerfileFileV1Chunker;
 pub use manifest_file_v1::ManifestFileV1Chunker;
+pub use code_text_paragraph_v1::CodeTextParagraphV1Chunker;

crates/kebab-chunk/src/manifest_file_v1.rs

@@ -44,6 +44,7 @@ impl Chunker for ManifestFileV1Chunker {
             "<manifest>",
             lang,
             VERSION_LABEL,
+            None,
         )?;
 
         tracing::debug!(

crates/kebab-chunk/src/md_heading_v1.rs

@@ -387,9 +387,7 @@ fn render_block_text(b: &Block) -> String {
         // alt keeps lexical search hits on filenames working even when
         // P6-1's filename auto-fill is bypassed.
         Block::ImageRef(i) => {
-            let alt = if !i.alt.is_empty() {
-                i.alt.clone()
-            } else {
+            let alt = if i.alt.is_empty() {
                 // P6-1 falls back to filename so this branch is
                 // defensive — keep it lest a future test fixture or
                 // synthetic block path skip the auto-fill.
@@ -399,17 +397,17 @@ fn render_block_text(b: &Block) -> String {
                     .filter(|s| !s.is_empty())
                     .unwrap_or("[image]")
                     .to_string()
+            } else {
+                i.alt.clone()
             };
             let ocr = i
                 .ocr
                 .as_ref()
-                .map(|o| o.joined.as_str())
-                .unwrap_or("");
+                .map_or("", |o| o.joined.as_str());
             let cap = i
                 .caption
                 .as_ref()
-                .map(|c| c.text.as_str())
-                .unwrap_or("");
+                .map_or("", |c| c.text.as_str());
             [alt.as_str(), ocr, cap]
                 .iter()
                 .filter(|s| !s.is_empty())

crates/kebab-chunk/src/pdf_page_v1.rs

@@ -450,7 +450,7 @@ mod tests {
         // chunk_ids stay distinct despite identical block_ids — the
         // per-chunk policy_hash variant is doing its job.
         let mut ids: Vec<&str> = chunks.iter().map(|c| c.chunk_id.0.as_str()).collect();
-        ids.sort();
+        ids.sort_unstable();
         let total = ids.len();
         ids.dedup();
         assert_eq!(ids.len(), total, "all chunk_ids must be unique");
@@ -668,7 +668,7 @@ mod tests {
         // chunk_ids stay distinct (the per-chunk hash variant keys off
         // char_start which is now strictly increasing).
         let mut ids: Vec<&str> = chunks.iter().map(|c| c.chunk_id.0.as_str()).collect();
-        ids.sort();
+        ids.sort_unstable();
         let total = ids.len();
         ids.dedup();
         assert_eq!(ids.len(), total, "chunk_ids must remain unique");

crates/kebab-chunk/src/tier2_shared.rs

@@ -25,6 +25,13 @@ pub(crate) fn policy_hash(policy: &ChunkPolicy) -> String {
 /// Emit one chunk for `(text, line_start..=line_end, symbol, lang)`, splitting
 /// into line-windows of at most `AST_CHUNK_MAX_LINES` if the slice is oversize.
 /// Mirrors the oversize path in `code_rust_ast_v1`'s `chunk` impl.
+///
+/// `base_split_key` is used as the `split_key` for the non-oversize single-chunk
+/// case. Callers that emit multiple chunks from the same document (e.g.
+/// `K8sManifestResourceV1Chunker` — one call per k8s resource) MUST pass
+/// `Some(line_start)` so that each call produces a distinct `chunk_id`.
+/// Single-chunk callers (dockerfile-file-v1, manifest-file-v1) pass `None` to
+/// keep chunk_ids stable (no sibling can collide when there's only one chunk).
 #[allow(clippy::too_many_arguments)]
 pub(crate) fn push_chunks_with_oversize(
     out: &mut Vec<Chunk>,
@@ -36,6 +43,7 @@ pub(crate) fn push_chunks_with_oversize(
     symbol: &str,
     lang: &str,
     chunker_version: &str,
+    base_split_key: Option<u32>,
 ) -> Result<()> {
     let n_lines = (line_end - line_start + 1).max(1);
     let cv = ChunkerVersion(chunker_version.to_string());
@@ -51,7 +59,7 @@ pub(crate) fn push_chunks_with_oversize(
             line_end,
             symbol,
             lang,
-            None,
+            base_split_key,
         ));
         return Ok(());
     }
@@ -88,7 +96,7 @@ pub(crate) fn push_chunks_with_oversize(
 /// for normal single-chunk emission.  Mirrors the `Some(part_ls)` / `None`
 /// split_key pattern in 1A-2.
 #[allow(clippy::too_many_arguments)]
-fn build_chunk(
+pub(crate) fn build_chunk(
     doc: &CanonicalDocument,
     chunker_version: &ChunkerVersion,
     base_policy_hash: &str,
@@ -105,7 +113,49 @@ fn build_chunk(
         symbol: Some(symbol.to_string()),
         lang: Some(lang.to_string()),
     };
+    build_chunk_from_span(doc, chunker_version, base_policy_hash, text, span, split_key)
+}
 
+/// Like `build_chunk` but emits `symbol: None`. Used by Tier 3 (per spec §9.3).
+///
+/// Accepts `policy: &ChunkPolicy` and `chunker_version: &str` (string slice)
+/// so callers don't need to pre-compute the hash and version wrapper.
+/// `split_key` is `Some(window_start)` for oversize line-window splits.
+#[allow(clippy::too_many_arguments)]
+pub(crate) fn build_chunk_no_symbol(
+    doc: &CanonicalDocument,
+    policy: &ChunkPolicy,
+    text: &str,
+    line_start: u32,
+    line_end: u32,
+    lang: &str,
+    chunker_version: &str,
+    split_key: Option<u32>,
+) -> Chunk {
+    let cv = ChunkerVersion(chunker_version.to_string());
+    let base_policy_hash = policy_hash(policy);
+    let span = SourceSpan::Code {
+        line_start,
+        line_end,
+        symbol: None,
+        lang: Some(lang.to_string()),
+    };
+    build_chunk_from_span(doc, &cv, &base_policy_hash, text, span, split_key)
+}
+
+/// Core chunk-building logic shared by `build_chunk` and `build_chunk_no_symbol`.
+///
+/// Takes a pre-built `SourceSpan` so the only difference between the two
+/// public helpers is whether `symbol` is `Some` or `None`.  All id/hash/
+/// token mechanics are identical.
+fn build_chunk_from_span(
+    doc: &CanonicalDocument,
+    chunker_version: &ChunkerVersion,
+    base_policy_hash: &str,
+    text: &str,
+    span: SourceSpan,
+    split_key: Option<u32>,
+) -> Chunk {
     // id_hash mirrors code_rust_ast_v1's make_chunk logic:
     //   split_key Some(k) => "{base_policy_hash}#L{k}"
     //   split_key None    => base_policy_hash
@@ -114,7 +164,7 @@ fn build_chunk(
         None => base_policy_hash.to_string(),
     };
 
-    // block_ids: Tier 2 chunkers have no per-block structure (the whole file
+    // block_ids: Tier 2/3 chunkers have no per-block structure (the whole file
     // is one Block::Code), so we pass an empty slice — same as using the doc-
     // level slice without explicit block granularity.
     let block_ids: Vec<BlockId> = vec![];

crates/kebab-chunk/tests/code_c_ast_snapshot.rs

@@ -0,0 +1,196 @@
+//! Snapshot test pinning the `Vec<Chunk>` JSON for a
+//! representative C code `CanonicalDocument`.
+//!
+//! This is an integration test. `kebab-parse-code` is intentionally NOT
+//! a dev-dep (design §6.3 / §8 boundary: AST extraction is parser-side).
+//! The `CanonicalDocument` is built inline from hand-crafted `Block::Code`
+//! units, which is the same pattern used in `code_go_ast_v1.rs`'s
+//! internal `code_doc` test helper.
+//!
+//! Set `UPDATE_SNAPSHOTS=1` to re-bake the baseline.
+
+use std::path::PathBuf;
+
+use kebab_chunk::CodeCAstV1Chunker;
+use kebab_core::{
+    AssetId, Block, CanonicalDocument, ChunkPolicy, Chunker, ChunkerVersion, CodeBlock, CommonBlock,
+    Lang, Metadata, ParserVersion, Provenance, SourceSpan, SourceType, TrustLevel, WorkspacePath,
+    id_for_block, id_for_doc,
+};
+use serde_json::Value;
+use time::OffsetDateTime;
+
+fn fixtures_dir() -> PathBuf {
+    PathBuf::from(env!("CARGO_MANIFEST_DIR"))
+        .join("tests")
+        .join("fixtures")
+}
+
+fn fixed_doc() -> CanonicalDocument {
+    let wp = WorkspacePath("projects/record.c".into());
+    let aid = AssetId("c".repeat(64));
+    // Pin parser_version so doc_id / block_ids are reproducible.
+    let pv = ParserVersion("code-c-v1".into());
+    let doc_id = id_for_doc(&wp, &aid, &pv);
+
+    // Representative units:
+    //  0. imports + defines              (lines 1–4,   ≤200)
+    //  1. status_t enum typedef          (lines 6–9,   ≤200)
+    //  2. record_t struct typedef        (lines 11–16, ≤200)
+    //  3. static counter decl glue       (line 18,     ≤200)
+    //  4. parse_record fn                (lines 20–23, ≤200)
+    //  5. print_record fn                (lines 25–27, ≤200)
+    //  6. main fn                        (lines 29–33, ≤200)
+    let raw_units: Vec<(&str, u32, u32, String)> = vec![
+        (
+            "<top-level>",
+            1,
+            18,
+            "#include <stdio.h>\n#include <stdlib.h>\n\n#define MAX_BUF 4096\n\ntypedef enum {\n    OK = 0,\n    ERR_PARSE,\n    ERR_IO,\n} status_t;\n\ntypedef struct {\n    int id;\n    char name[64];\n    status_t status;\n} record_t;\n\nstatic int counter = 0;".to_string(),
+        ),
+        (
+            "parse_record",
+            20,
+            23,
+            "int parse_record(const char *line, record_t *out) {\n    if (line == NULL || out == NULL) return ERR_PARSE;\n    return OK;\n}".to_string(),
+        ),
+        (
+            "print_record",
+            25,
+            27,
+            "void print_record(const record_t *r) {\n    printf(\"[%d] %s (status=%d)\\n\", r->id, r->name, r->status);\n}".to_string(),
+        ),
+        (
+            "main",
+            29,
+            33,
+            "int main(void) {\n    record_t r = { .id = 1, .name = \"foo\", .status = OK };\n    print_record(&r);\n    return 0;\n}".to_string(),
+        ),
+    ];
+
+    let blocks: Vec<Block> = raw_units
+        .iter()
+        .enumerate()
+        .map(|(i, (sym, ls, le, code))| {
+            let span = SourceSpan::Code {
+                line_start: *ls,
+                line_end: *le,
+                symbol: Some((*sym).to_string()),
+                lang: Some("c".into()),
+            };
+            let bid = id_for_block(&doc_id, "code", &[], i as u32, &span);
+            Block::Code(CodeBlock {
+                common: CommonBlock {
+                    block_id: bid,
+                    heading_path: vec![],
+                    source_span: span,
+                },
+                lang: Some("c".into()),
+                code: code.clone(),
+            })
+        })
+        .collect();
+
+    CanonicalDocument {
+        doc_id,
+        source_asset_id: aid,
+        workspace_path: wp,
+        title: "record.c".into(),
+        lang: Lang("und".into()),
+        blocks,
+        metadata: Metadata {
+            aliases: vec![],
+            tags: vec![],
+            created_at: OffsetDateTime::from_unix_timestamp(1_700_000_000).unwrap(),
+            updated_at: OffsetDateTime::from_unix_timestamp(1_700_000_000).unwrap(),
+            source_type: SourceType::Note,
+            trust_level: TrustLevel::Primary,
+            user_id_alias: None,
+            user: Default::default(),
+            repo: Some("kebab".into()),
+            git_branch: Some("main".into()),
+            git_commit: Some("0".repeat(40)),
+            code_lang: Some("c".into()),
+        },
+        provenance: Provenance { events: vec![] },
+        parser_version: pv,
+        schema_version: 1,
+        doc_version: 1,
+        last_chunker_version: None,
+        last_embedding_version: None,
+    }
+}
+
+fn fixed_policy() -> ChunkPolicy {
+    ChunkPolicy {
+        target_tokens: 500,
+        overlap_tokens: 80,
+        respect_markdown_headings: false,
+        chunker_version: ChunkerVersion("code-c-ast-v1".into()),
+    }
+}
+
+#[test]
+fn code_c_ast_chunks_snapshot() {
+    let doc = fixed_doc();
+    let policy = fixed_policy();
+
+    let chunks = CodeCAstV1Chunker.chunk(&doc, &policy).expect("chunk");
+    let actual = serde_json::to_value(&chunks).unwrap();
+
+    let dir = fixtures_dir();
+    let baseline_path = dir.join("code-sample.c.chunks.snapshot.json");
+    let baseline_text = match std::fs::read_to_string(&baseline_path) {
+        Ok(s) => s,
+        Err(_) if std::env::var("UPDATE_SNAPSHOTS").is_ok() => {
+            std::fs::create_dir_all(&dir).unwrap();
+            let pretty = serde_json::to_string_pretty(&actual).unwrap();
+            std::fs::write(&baseline_path, format!("{pretty}\n")).unwrap();
+            return;
+        }
+        Err(e) => panic!(
+            "missing baseline {}; run with UPDATE_SNAPSHOTS=1 to create: {e}",
+            baseline_path.display()
+        ),
+    };
+    let expected: Value = serde_json::from_str(&baseline_text).expect("baseline parses as json");
+
+    if actual != expected {
+        if std::env::var("UPDATE_SNAPSHOTS").is_ok() {
+            let pretty = serde_json::to_string_pretty(&actual).unwrap();
+            std::fs::write(&baseline_path, format!("{pretty}\n")).unwrap();
+            eprintln!("updated baseline {}", baseline_path.display());
+            return;
+        }
+        let pretty = serde_json::to_string_pretty(&actual).unwrap();
+        panic!(
+            "code-c-ast-v1 chunks snapshot drift\n\
+             --- expected ({}) ---\n{baseline_text}\n\
+             --- actual ---\n{pretty}\n\
+             If intentional, re-run with UPDATE_SNAPSHOTS=1.",
+            baseline_path.display()
+        );
+    }
+}
+
+/// Determinism cross-check: re-running the same pipeline yields the same
+/// chunk_ids byte-for-byte.
+#[test]
+fn code_c_ast_chunks_are_deterministic() {
+    let policy = fixed_policy();
+    let baseline: Vec<String> = CodeCAstV1Chunker
+        .chunk(&fixed_doc(), &policy)
+        .unwrap()
+        .into_iter()
+        .map(|c| c.chunk_id.0)
+        .collect();
+    for _ in 0..5 {
+        let again: Vec<String> = CodeCAstV1Chunker
+            .chunk(&fixed_doc(), &policy)
+            .unwrap()
+            .into_iter()
+            .map(|c| c.chunk_id.0)
+            .collect();
+        assert_eq!(again, baseline);
+    }
+}

crates/kebab-chunk/tests/code_cpp_ast_snapshot.rs

@@ -0,0 +1,325 @@
+//! Snapshot test pinning the `Vec<Chunk>` JSON for a
+//! representative C++ code `CanonicalDocument`.
+//!
+//! Two complementary tests:
+//! 1. `code_cpp_ast_chunks_snapshot` — hand-built `fixed_doc()` validates the
+//!    chunker's 1:1 mapping (design §6.3 / §8 boundary: no parse-code dep needed).
+//! 2. `code_cpp_ast_extractor_snapshot` — invokes `CppAstExtractor` against the
+//!    real `tests/fixtures/sample.cpp` fixture, validating the extractor → chunker
+//!    end-to-end pipeline. `kebab-parse-code` is a dev-dep (same pattern as
+//!    `kebab-parse-md` in Markdown snapshot tests).
+//!
+//! Set `UPDATE_SNAPSHOTS=1` to re-bake the baseline.
+
+use std::path::PathBuf;
+
+use kebab_chunk::CodeCppAstV1Chunker;
+use kebab_core::{
+    AssetId, Block, CanonicalDocument, ChunkPolicy, Chunker, ChunkerVersion, CodeBlock, CommonBlock,
+    Lang, Metadata, ParserVersion, Provenance, SourceSpan, SourceType, TrustLevel, WorkspacePath,
+    id_for_block, id_for_doc,
+};
+use kebab_parse_code::CppAstExtractor;
+use serde_json::Value;
+use time::OffsetDateTime;
+
+fn fixtures_dir() -> PathBuf {
+    PathBuf::from(env!("CARGO_MANIFEST_DIR"))
+        .join("tests")
+        .join("fixtures")
+}
+
+fn fixed_doc() -> CanonicalDocument {
+    let wp = WorkspacePath("projects/record.cpp".into());
+    let aid = AssetId("c".repeat(64));
+    // Pin parser_version so doc_id / block_ids are reproducible.
+    let pv = ParserVersion("code-cpp-v1".into());
+    let doc_id = id_for_doc(&wp, &aid, &pv);
+
+    // Representative units (C++ specific):
+    //  0. includes + namespace opening  (lines 1–4,   ≤200)
+    //  1. class definition              (lines 6–20,  ≤200)
+    //  2. template function             (lines 22–25, ≤200)
+    //  3. namespace closing + free fn   (lines 27–29, ≤200)
+    //  4. main fn                       (lines 31–34, ≤200)
+    let raw_units: Vec<(&str, u32, u32, String)> = vec![
+        (
+            "<top-level>",
+            1,
+            4,
+            "#include <string>\n#include <vector>\n\nnamespace kebab {".to_string(),
+        ),
+        (
+            "kebab::chunk::MdHeadingV1Chunker",
+            6,
+            20,
+            "class MdHeadingV1Chunker {\npublic:\n    MdHeadingV1Chunker() = default;\n    ~MdHeadingV1Chunker() = default;\n\n    std::string chunk_doc(const std::string& doc) {\n        return doc;\n    }\n\n    int operator()(int x) const {\n        return x * 2;\n    }\n\nprivate:\n    int counter_ = 0;\n};".to_string(),
+        ),
+        (
+            "kebab::identity",
+            22,
+            25,
+            "template <typename T>\nT identity(T value) {\n    return value;\n}".to_string(),
+        ),
+        (
+            "kebab::global_helper",
+            27,
+            29,
+            "void global_helper() {\n    // free function in kebab namespace\n}".to_string(),
+        ),
+        (
+            "main",
+            31,
+            34,
+            "int main() {\n    kebab::chunk::MdHeadingV1Chunker c;\n    return 0;\n}".to_string(),
+        ),
+    ];
+
+    let blocks: Vec<Block> = raw_units
+        .iter()
+        .enumerate()
+        .map(|(i, (sym, ls, le, code))| {
+            let span = SourceSpan::Code {
+                line_start: *ls,
+                line_end: *le,
+                symbol: Some((*sym).to_string()),
+                lang: Some("cpp".into()),
+            };
+            let bid = id_for_block(&doc_id, "code", &[], i as u32, &span);
+            Block::Code(CodeBlock {
+                common: CommonBlock {
+                    block_id: bid,
+                    heading_path: vec![],
+                    source_span: span,
+                },
+                lang: Some("cpp".into()),
+                code: code.clone(),
+            })
+        })
+        .collect();
+
+    CanonicalDocument {
+        doc_id,
+        source_asset_id: aid,
+        workspace_path: wp,
+        title: "record.cpp".into(),
+        lang: Lang("und".into()),
+        blocks,
+        metadata: Metadata {
+            aliases: vec![],
+            tags: vec![],
+            created_at: OffsetDateTime::from_unix_timestamp(1_700_000_000).unwrap(),
+            updated_at: OffsetDateTime::from_unix_timestamp(1_700_000_000).unwrap(),
+            source_type: SourceType::Note,
+            trust_level: TrustLevel::Primary,
+            user_id_alias: None,
+            user: Default::default(),
+            repo: Some("kebab".into()),
+            git_branch: Some("main".into()),
+            git_commit: Some("0".repeat(40)),
+            code_lang: Some("cpp".into()),
+        },
+        provenance: Provenance { events: vec![] },
+        parser_version: pv,
+        schema_version: 1,
+        doc_version: 1,
+        last_chunker_version: None,
+        last_embedding_version: None,
+    }
+}
+
+fn fixed_policy() -> ChunkPolicy {
+    ChunkPolicy {
+        target_tokens: 500,
+        overlap_tokens: 80,
+        respect_markdown_headings: false,
+        chunker_version: ChunkerVersion("code-cpp-ast-v1".into()),
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Helper: run the real CppAstExtractor against tests/fixtures/sample.cpp
+// ---------------------------------------------------------------------------
+
+fn extract_cpp_fixture() -> CanonicalDocument {
+    use kebab_core::{
+        AssetId, AssetStorage, Checksum, ExtractConfig, ExtractContext, Extractor, RawAsset,
+        SourceUri, WorkspacePath,
+    };
+    use std::path::PathBuf;
+
+    let bytes = std::fs::read(fixtures_dir().join("sample.cpp")).expect("read sample.cpp fixture");
+    let src = String::from_utf8(bytes).expect("fixture is valid UTF-8");
+    let wp = WorkspacePath("tests/fixtures/sample.cpp".to_string());
+    let asset = RawAsset {
+        asset_id: AssetId("e".repeat(64)),
+        source_uri: SourceUri::File(PathBuf::from("tests/fixtures/sample.cpp")),
+        workspace_path: wp,
+        media_type: kebab_core::MediaType::Code("cpp".to_string()),
+        byte_len: src.len() as u64,
+        checksum: Checksum("f".repeat(64)),
+        discovered_at: time::OffsetDateTime::from_unix_timestamp(1_700_000_000).unwrap(),
+        stored: AssetStorage::Reference {
+            path: PathBuf::from("tests/fixtures/sample.cpp"),
+            sha: Checksum("f".repeat(64)),
+        },
+    };
+    let cfg = ExtractConfig::default();
+    let root = PathBuf::from("/tmp");
+    let ctx = ExtractContext {
+        asset: &asset,
+        workspace_root: &root,
+        config: &cfg,
+    };
+    CppAstExtractor::new().extract(&ctx, src.as_bytes()).unwrap()
+}
+
+// ---------------------------------------------------------------------------
+// Test 1 (hand-built): chunker-only 1:1 mapping validation
+// ---------------------------------------------------------------------------
+
+#[test]
+fn code_cpp_ast_chunks_snapshot() {
+    let doc = fixed_doc();
+    let policy = fixed_policy();
+
+    let chunks = CodeCppAstV1Chunker.chunk(&doc, &policy).expect("chunk");
+    let actual = serde_json::to_value(&chunks).unwrap();
+
+    let dir = fixtures_dir();
+    let baseline_path = dir.join("code-sample.cpp.chunks.snapshot.json");
+    let baseline_text = match std::fs::read_to_string(&baseline_path) {
+        Ok(s) => s,
+        Err(_) if std::env::var("UPDATE_SNAPSHOTS").is_ok() => {
+            std::fs::create_dir_all(&dir).unwrap();
+            let pretty = serde_json::to_string_pretty(&actual).unwrap();
+            std::fs::write(&baseline_path, format!("{pretty}\n")).unwrap();
+            return;
+        }
+        Err(e) => panic!(
+            "missing baseline {}; run with UPDATE_SNAPSHOTS=1 to create: {e}",
+            baseline_path.display()
+        ),
+    };
+    let expected: Value = serde_json::from_str(&baseline_text).expect("baseline parses as json");
+
+    if actual != expected {
+        if std::env::var("UPDATE_SNAPSHOTS").is_ok() {
+            let pretty = serde_json::to_string_pretty(&actual).unwrap();
+            std::fs::write(&baseline_path, format!("{pretty}\n")).unwrap();
+            eprintln!("updated baseline {}", baseline_path.display());
+            return;
+        }
+        let pretty = serde_json::to_string_pretty(&actual).unwrap();
+        panic!(
+            "code-cpp-ast-v1 chunks snapshot drift\n\
+             --- expected ({}) ---\n{baseline_text}\n\
+             --- actual ---\n{pretty}\n\
+             If intentional, re-run with UPDATE_SNAPSHOTS=1.",
+            baseline_path.display()
+        );
+    }
+}
+
+/// Determinism cross-check: re-running the same pipeline yields the same
+/// chunk_ids byte-for-byte.
+#[test]
+fn code_cpp_ast_chunks_are_deterministic() {
+    let policy = fixed_policy();
+    let baseline: Vec<String> = CodeCppAstV1Chunker
+        .chunk(&fixed_doc(), &policy)
+        .unwrap()
+        .into_iter()
+        .map(|c| c.chunk_id.0)
+        .collect();
+    for _ in 0..5 {
+        let again: Vec<String> = CodeCppAstV1Chunker
+            .chunk(&fixed_doc(), &policy)
+            .unwrap()
+            .into_iter()
+            .map(|c| c.chunk_id.0)
+            .collect();
+        assert_eq!(again, baseline);
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Test 2 (real extractor): end-to-end extractor → chunker pipeline
+// ---------------------------------------------------------------------------
+
+/// Validates that the real `CppAstExtractor` processes `sample.cpp` and
+/// emits the expected set of symbols through the full chunker pipeline.
+///
+/// `sample.cpp` contains:
+/// - `#include` directives + nested namespace `kebab::chunk` → glue + struct unit
+/// - `class MdHeadingV1Chunker` with methods (ctor, dtor, chunk_doc, operator())
+/// - `template <typename T> T identity(T value)` (template fn)
+/// - `void kebab::global_helper()` (free fn in namespace)
+/// - `int main()` (global free fn)
+#[test]
+fn code_cpp_ast_extractor_snapshot() {
+    let doc = extract_cpp_fixture();
+
+    // Verify the extractor emits all expected named units.
+    let block_syms: Vec<Option<String>> = doc.blocks.iter().filter_map(|b| match b {
+        Block::Code(c) => match &c.common.source_span {
+            SourceSpan::Code { symbol, .. } => Some(symbol.clone()),
+            _ => None,
+        },
+        _ => None,
+    }).collect();
+
+    // Must include namespace-qualified class and its methods
+    assert!(
+        block_syms.iter().any(|s| s.as_deref() == Some("kebab::chunk::MdHeadingV1Chunker")),
+        "class unit missing: {block_syms:?}"
+    );
+    assert!(
+        block_syms.iter().any(|s| s.as_deref() == Some("kebab::chunk::MdHeadingV1Chunker::MdHeadingV1Chunker")),
+        "ctor unit missing: {block_syms:?}"
+    );
+    assert!(
+        block_syms.iter().any(|s| s.as_deref() == Some("kebab::chunk::MdHeadingV1Chunker::~MdHeadingV1Chunker")),
+        "dtor unit missing: {block_syms:?}"
+    );
+    assert!(
+        block_syms.iter().any(|s| s.as_deref() == Some("kebab::chunk::MdHeadingV1Chunker::chunk_doc")),
+        "chunk_doc unit missing: {block_syms:?}"
+    );
+    assert!(
+        block_syms.iter().any(|s| s.as_deref() == Some("kebab::chunk::MdHeadingV1Chunker::operator()")),
+        "operator() unit missing: {block_syms:?}"
+    );
+    // Template function (inside kebab::chunk namespace in the fixture)
+    assert!(
+        block_syms.iter().any(|s| s.as_deref() == Some("kebab::chunk::identity")),
+        "identity template fn unit missing: {block_syms:?}"
+    );
+    // Free function in outer namespace
+    assert!(
+        block_syms.iter().any(|s| s.as_deref() == Some("kebab::global_helper")),
+        "global_helper unit missing: {block_syms:?}"
+    );
+    // Global main
+    assert!(
+        block_syms.iter().any(|s| s.as_deref() == Some("main")),
+        "main unit missing: {block_syms:?}"
+    );
+}
+
+/// End-to-end chunker output from real extractor is deterministic.
+#[test]
+fn code_cpp_ast_extractor_chunks_deterministic() {
+    let doc1 = extract_cpp_fixture();
+    let doc2 = extract_cpp_fixture();
+    assert_eq!(doc1.blocks, doc2.blocks, "extractor output non-deterministic");
+
+    let policy = fixed_policy();
+    let chunks1 = CodeCppAstV1Chunker.chunk(&doc1, &policy).unwrap();
+    let chunks2 = CodeCppAstV1Chunker.chunk(&doc2, &policy).unwrap();
+    assert_eq!(
+        chunks1.iter().map(|c| c.chunk_id.0.clone()).collect::<Vec<_>>(),
+        chunks2.iter().map(|c| c.chunk_id.0.clone()).collect::<Vec<_>>(),
+        "chunker output non-deterministic"
+    );
+}

crates/kebab-chunk/tests/code_text_paragraph_v1.rs

@@ -0,0 +1,270 @@
+//! Behavioural tests for `CodeTextParagraphV1Chunker`.
+//!
+//! Documents are constructed manually (no kebab-parse-code dependency) by
+//! placing raw text into a single `Block::Code`, mirroring the pattern used
+//! in `k8s_manifest_resource_v1.rs`.
+
+use std::path::PathBuf;
+
+use kebab_chunk::CodeTextParagraphV1Chunker;
+use kebab_core::{
+    AssetId, Block, CanonicalDocument, ChunkPolicy, Chunker, ChunkerVersion, CodeBlock,
+    CommonBlock, Lang, Metadata, ParserVersion, Provenance, SourceSpan, SourceType, TrustLevel,
+    WorkspacePath, id_for_block, id_for_doc,
+};
+use time::OffsetDateTime;
+
+// ── helpers ──────────────────────────────────────────────────────────────────
+
+fn fixtures_dir() -> PathBuf {
+    PathBuf::from(env!("CARGO_MANIFEST_DIR"))
+        .join("tests")
+        .join("fixtures")
+}
+
+/// Build a `CanonicalDocument` with a single `Block::Code` containing `text`
+/// and the supplied `lang` label.
+fn text_doc(lang: &str, text: &str) -> CanonicalDocument {
+    let wp = WorkspacePath("scripts/sample.sh".into());
+    let aid = AssetId("d".repeat(64));
+    let pv = ParserVersion("code-text-paragraph-v1".into());
+    let doc_id = id_for_doc(&wp, &aid, &pv);
+
+    let line_count = text.lines().count() as u32;
+    let span = SourceSpan::Code {
+        line_start: 1,
+        line_end: line_count.max(1),
+        symbol: None,
+        lang: Some(lang.into()),
+    };
+    let bid = id_for_block(&doc_id, "code", &[], 0, &span);
+    let block = Block::Code(CodeBlock {
+        common: CommonBlock {
+            block_id: bid,
+            heading_path: vec![],
+            source_span: span,
+        },
+        lang: Some(lang.into()),
+        code: text.to_string(),
+    });
+
+    CanonicalDocument {
+        doc_id,
+        source_asset_id: aid,
+        workspace_path: wp,
+        title: "sample.sh".into(),
+        lang: Lang("und".into()),
+        blocks: vec![block],
+        metadata: Metadata {
+            aliases: vec![],
+            tags: vec![],
+            created_at: OffsetDateTime::from_unix_timestamp(1_700_000_000).unwrap(),
+            updated_at: OffsetDateTime::from_unix_timestamp(1_700_000_000).unwrap(),
+            source_type: SourceType::Note,
+            trust_level: TrustLevel::Primary,
+            user_id_alias: None,
+            user: Default::default(),
+            repo: Some("kebab".into()),
+            git_branch: Some("main".into()),
+            git_commit: Some("0".repeat(40)),
+            code_lang: Some(lang.into()),
+        },
+        provenance: Provenance { events: vec![] },
+        parser_version: pv,
+        schema_version: 1,
+        doc_version: 1,
+        last_chunker_version: None,
+        last_embedding_version: None,
+    }
+}
+
+fn policy() -> ChunkPolicy {
+    ChunkPolicy {
+        target_tokens: 500,
+        overlap_tokens: 80,
+        respect_markdown_headings: false,
+        chunker_version: ChunkerVersion("code-text-paragraph-v1".into()),
+    }
+}
+
+// ── tests ─────────────────────────────────────────────────────────────────────
+
+/// `sample_shell.sh` has 4 paragraphs separated by 3 blank lines:
+///   - paragraph 1: lines 1-2  (shebang + set -euo pipefail)
+///   - paragraph 2: lines 4-7  (env setup block)
+///   - paragraph 3: lines 9-11 (ingest block)
+///   - paragraph 4: lines 13-15 (report block)
+///
+/// We assert:
+///   - exactly 4 chunks (one per paragraph)
+///   - all symbols are None (Tier 3 spec §9.3)
+///   - all langs are "shell"
+///   - line ranges are strictly ascending and do NOT include the blank lines
+///     (lines 3, 8, 12 must not appear in any range)
+#[test]
+fn shell_multi_paragraph_splits_on_blank_lines() {
+    let fixture_path = fixtures_dir().join("sample_shell.sh");
+    let text = std::fs::read_to_string(&fixture_path)
+        .unwrap_or_else(|e| panic!("cannot read fixture {}: {e}", fixture_path.display()));
+
+    let doc = text_doc("shell", &text);
+    let chunks = CodeTextParagraphV1Chunker
+        .chunk(&doc, &policy())
+        .expect("chunk");
+
+    assert_eq!(
+        chunks.len(),
+        4,
+        "expected 4 chunks (one per paragraph), got {}: {chunks:#?}",
+        chunks.len()
+    );
+
+    // All symbols must be None (Tier 3 requirement).
+    for (i, chunk) in chunks.iter().enumerate() {
+        match &chunk.source_spans[0] {
+            SourceSpan::Code { symbol, .. } => {
+                assert!(
+                    symbol.is_none(),
+                    "chunk[{i}] symbol must be None for Tier 3 chunker, got {symbol:?}"
+                );
+            }
+            other => panic!("chunk[{i}]: expected Code span, got {other:?}"),
+        }
+    }
+
+    // All langs must be "shell".
+    for (i, chunk) in chunks.iter().enumerate() {
+        match &chunk.source_spans[0] {
+            SourceSpan::Code { lang, .. } => {
+                assert_eq!(
+                    lang.as_deref(),
+                    Some("shell"),
+                    "chunk[{i}] lang must be 'shell', got {lang:?}"
+                );
+            }
+            other => panic!("chunk[{i}]: expected Code span, got {other:?}"),
+        }
+    }
+
+    // Line ranges must be strictly ascending with no overlap,
+    // and blank lines (3, 8, 12) must not be included in any range.
+    let expected_ranges: &[(u32, u32)] = &[(1, 2), (4, 7), (9, 11), (13, 15)];
+    let actual_ranges: Vec<(u32, u32)> = chunks
+        .iter()
+        .map(|c| match &c.source_spans[0] {
+            SourceSpan::Code {
+                line_start,
+                line_end,
+                ..
+            } => (*line_start, *line_end),
+            other => panic!("expected Code span, got {other:?}"),
+        })
+        .collect();
+
+    assert_eq!(
+        actual_ranges, expected_ranges,
+        "line ranges mismatch: got {actual_ranges:?}, expected {expected_ranges:?}"
+    );
+}
+
+/// `sample_long_paragraph.txt` has exactly 200 non-blank lines and no blank
+/// lines, so the entire file is one paragraph.  200 > 80 (FALLBACK_LINES_PER_CHUNK),
+/// so the oversize window split fires with stride 60:
+///   - window 1: lines 1-80
+///   - window 2: lines 61-140
+///   - window 3: lines 121-200
+///
+/// All chunk_ids must be distinct (the #L{window_start} split_key suffix).
+#[test]
+fn single_long_paragraph_line_window_split() {
+    let fixture_path = fixtures_dir().join("sample_long_paragraph.txt");
+    let text = std::fs::read_to_string(&fixture_path)
+        .unwrap_or_else(|e| panic!("cannot read fixture {}: {e}", fixture_path.display()));
+
+    assert_eq!(
+        text.lines().count(),
+        200,
+        "fixture must have exactly 200 lines"
+    );
+
+    let doc = text_doc("shell", &text);
+    let chunks = CodeTextParagraphV1Chunker
+        .chunk(&doc, &policy())
+        .expect("chunk");
+
+    assert_eq!(
+        chunks.len(),
+        3,
+        "expected 3 window chunks for 200-line paragraph, got {}: {chunks:#?}",
+        chunks.len()
+    );
+
+    let expected_ranges: &[(u32, u32)] = &[(1, 80), (61, 140), (121, 200)];
+    let actual_ranges: Vec<(u32, u32)> = chunks
+        .iter()
+        .map(|c| match &c.source_spans[0] {
+            SourceSpan::Code {
+                line_start,
+                line_end,
+                ..
+            } => (*line_start, *line_end),
+            other => panic!("expected Code span, got {other:?}"),
+        })
+        .collect();
+
+    assert_eq!(
+        actual_ranges, expected_ranges,
+        "window ranges mismatch: got {actual_ranges:?}, expected {expected_ranges:?}"
+    );
+
+    // All chunk_ids must be distinct (#L{window_start} suffix differentiates them).
+    let ids: std::collections::HashSet<_> = chunks.iter().map(|c| c.chunk_id.clone()).collect();
+    assert_eq!(
+        ids.len(),
+        chunks.len(),
+        "oversize window chunks must have distinct chunk_ids"
+    );
+}
+
+/// An empty source file (no non-blank lines) must yield zero chunks.
+#[test]
+fn empty_file_emits_zero_chunks() {
+    let doc = text_doc("shell", "");
+    let chunks = CodeTextParagraphV1Chunker
+        .chunk(&doc, &policy())
+        .expect("chunk");
+
+    assert_eq!(
+        chunks.len(),
+        0,
+        "empty file must yield 0 chunks, got {}: {chunks:#?}",
+        chunks.len()
+    );
+}
+
+/// The `lang` field on each emitted chunk must match the `lang` passed to
+/// `text_doc`, regardless of content.  `symbol` must be `None` (Tier 3 spec).
+#[test]
+fn lang_field_preserved_from_input_doc() {
+    let doc = text_doc("yaml", "key1: value1\nkey2: value2\n");
+    let chunks = CodeTextParagraphV1Chunker
+        .chunk(&doc, &policy())
+        .expect("chunk");
+
+    assert!(!chunks.is_empty(), "expected at least one chunk");
+
+    match &chunks[0].source_spans[0] {
+        SourceSpan::Code { lang, symbol, .. } => {
+            assert_eq!(
+                lang.as_deref(),
+                Some("yaml"),
+                "lang must be 'yaml', got {lang:?}"
+            );
+            assert!(
+                symbol.is_none(),
+                "symbol must be None for Tier 3 chunker, got {symbol:?}"
+            );
+        }
+        other => panic!("expected Code span, got {other:?}"),
+    }
+}

crates/kebab-chunk/tests/fixtures/code-sample.c.chunks.snapshot.json

@@ -0,0 +1,86 @@
+[
+  {
+    "block_ids": [
+      "8149e12ca002489acb4a0f74c97a061a"
+    ],
+    "chunk_id": "ec3cf06ae56c8e9796bbc9196438b7c5",
+    "chunker_version": "code-c-ast-v1",
+    "doc_id": "6bec42dd593920a060541db16c4e8e45",
+    "heading_path": [],
+    "policy_hash": "ecfad2ec1223662d",
+    "source_spans": [
+      {
+        "kind": "code",
+        "lang": "c",
+        "line_end": 18,
+        "line_start": 1,
+        "symbol": "<top-level>"
+      }
+    ],
+    "text": "#include <stdio.h>\n#include <stdlib.h>\n\n#define MAX_BUF 4096\n\ntypedef enum {\n    OK = 0,\n    ERR_PARSE,\n    ERR_IO,\n} status_t;\n\ntypedef struct {\n    int id;\n    char name[64];\n    status_t status;\n} record_t;\n\nstatic int counter = 0;",
+    "token_estimate": 78
+  },
+  {
+    "block_ids": [
+      "1baaa89f21a47b2f32d6396a24a85454"
+    ],
+    "chunk_id": "c2d7a81c898106733ef2e703774a6a4a",
+    "chunker_version": "code-c-ast-v1",
+    "doc_id": "6bec42dd593920a060541db16c4e8e45",
+    "heading_path": [],
+    "policy_hash": "ecfad2ec1223662d",
+    "source_spans": [
+      {
+        "kind": "code",
+        "lang": "c",
+        "line_end": 23,
+        "line_start": 20,
+        "symbol": "parse_record"
+      }
+    ],
+    "text": "int parse_record(const char *line, record_t *out) {\n    if (line == NULL || out == NULL) return ERR_PARSE;\n    return OK;\n}",
+    "token_estimate": 41
+  },
+  {
+    "block_ids": [
+      "8d0e14cbcc6d1e92d7878ab796ea68b8"
+    ],
+    "chunk_id": "0e4d7b131ab64eba03b51903b5d8f96d",
+    "chunker_version": "code-c-ast-v1",
+    "doc_id": "6bec42dd593920a060541db16c4e8e45",
+    "heading_path": [],
+    "policy_hash": "ecfad2ec1223662d",
+    "source_spans": [
+      {
+        "kind": "code",
+        "lang": "c",
+        "line_end": 27,
+        "line_start": 25,
+        "symbol": "print_record"
+      }
+    ],
+    "text": "void print_record(const record_t *r) {\n    printf(\"[%d] %s (status=%d)\\n\", r->id, r->name, r->status);\n}",
+    "token_estimate": 35
+  },
+  {
+    "block_ids": [
+      "9c2ede84423871b615d48c38fefb1853"
+    ],
+    "chunk_id": "e076f8edb2ff141d7e99b4106bb95157",
+    "chunker_version": "code-c-ast-v1",
+    "doc_id": "6bec42dd593920a060541db16c4e8e45",
+    "heading_path": [],
+    "policy_hash": "ecfad2ec1223662d",
+    "source_spans": [
+      {
+        "kind": "code",
+        "lang": "c",
+        "line_end": 33,
+        "line_start": 29,
+        "symbol": "main"
+      }
+    ],
+    "text": "int main(void) {\n    record_t r = { .id = 1, .name = \"foo\", .status = OK };\n    print_record(&r);\n    return 0;\n}",
+    "token_estimate": 38
+  }
+]

crates/kebab-chunk/tests/fixtures/code-sample.cpp.chunks.snapshot.json

@@ -0,0 +1,107 @@
+[
+  {
+    "block_ids": [
+      "53292605459065d170cd36c118e20546"
+    ],
+    "chunk_id": "50a5b324300d9082eac4ce2a422810e1",
+    "chunker_version": "code-cpp-ast-v1",
+    "doc_id": "fff1e1f0a7ff70ef682937470e5d1d28",
+    "heading_path": [],
+    "policy_hash": "71f3c07bb9ec1d09",
+    "source_spans": [
+      {
+        "kind": "code",
+        "lang": "cpp",
+        "line_end": 4,
+        "line_start": 1,
+        "symbol": "<top-level>"
+      }
+    ],
+    "text": "#include <string>\n#include <vector>\n\nnamespace kebab {",
+    "token_estimate": 18
+  },
+  {
+    "block_ids": [
+      "f349acad94c9fa4cf9ad1c0a93e83610"
+    ],
+    "chunk_id": "0e6bc7c522665af8a4b0f66afb9d29c8",
+    "chunker_version": "code-cpp-ast-v1",
+    "doc_id": "fff1e1f0a7ff70ef682937470e5d1d28",
+    "heading_path": [],
+    "policy_hash": "71f3c07bb9ec1d09",
+    "source_spans": [
+      {
+        "kind": "code",
+        "lang": "cpp",
+        "line_end": 20,
+        "line_start": 6,
+        "symbol": "kebab::chunk::MdHeadingV1Chunker"
+      }
+    ],
+    "text": "class MdHeadingV1Chunker {\npublic:\n    MdHeadingV1Chunker() = default;\n    ~MdHeadingV1Chunker() = default;\n\n    std::string chunk_doc(const std::string& doc) {\n        return doc;\n    }\n\n    int operator()(int x) const {\n        return x * 2;\n    }\n\nprivate:\n    int counter_ = 0;\n};",
+    "token_estimate": 95
+  },
+  {
+    "block_ids": [
+      "8b9811387717d0bd4abf84abcc35b8b1"
+    ],
+    "chunk_id": "d9326d252905b665b2adb9a416c20451",
+    "chunker_version": "code-cpp-ast-v1",
+    "doc_id": "fff1e1f0a7ff70ef682937470e5d1d28",
+    "heading_path": [],
+    "policy_hash": "71f3c07bb9ec1d09",
+    "source_spans": [
+      {
+        "kind": "code",
+        "lang": "cpp",
+        "line_end": 25,
+        "line_start": 22,
+        "symbol": "kebab::identity"
+      }
+    ],
+    "text": "template <typename T>\nT identity(T value) {\n    return value;\n}",
+    "token_estimate": 21
+  },
+  {
+    "block_ids": [
+      "1754cb6b971f6a4cb292f144a4f0570b"
+    ],
+    "chunk_id": "56ee5f991de4a413c016da8dc4acfc35",
+    "chunker_version": "code-cpp-ast-v1",
+    "doc_id": "fff1e1f0a7ff70ef682937470e5d1d28",
+    "heading_path": [],
+    "policy_hash": "71f3c07bb9ec1d09",
+    "source_spans": [
+      {
+        "kind": "code",
+        "lang": "cpp",
+        "line_end": 29,
+        "line_start": 27,
+        "symbol": "kebab::global_helper"
+      }
+    ],
+    "text": "void global_helper() {\n    // free function in kebab namespace\n}",
+    "token_estimate": 22
+  },
+  {
+    "block_ids": [
+      "14b5f3393d6d25f822f5b70763d24acd"
+    ],
+    "chunk_id": "c0d7c043cdd575c530db3909b54cc906",
+    "chunker_version": "code-cpp-ast-v1",
+    "doc_id": "fff1e1f0a7ff70ef682937470e5d1d28",
+    "heading_path": [],
+    "policy_hash": "71f3c07bb9ec1d09",
+    "source_spans": [
+      {
+        "kind": "code",
+        "lang": "cpp",
+        "line_end": 34,
+        "line_start": 31,
+        "symbol": "main"
+      }
+    ],
+    "text": "int main() {\n    kebab::chunk::MdHeadingV1Chunker c;\n    return 0;\n}",
+    "token_estimate": 23
+  }
+]

crates/kebab-chunk/tests/fixtures/sample.c

@@ -0,0 +1,33 @@
+#include <stdio.h>
+#include <stdlib.h>
+
+#define MAX_BUF 4096
+
+typedef enum {
+    OK = 0,
+    ERR_PARSE,
+    ERR_IO,
+} status_t;
+
+typedef struct {
+    int id;
+    char name[64];
+    status_t status;
+} record_t;
+
+static int counter = 0;
+
+int parse_record(const char *line, record_t *out) {
+    if (line == NULL || out == NULL) return ERR_PARSE;
+    return OK;
+}
+
+void print_record(const record_t *r) {
+    printf("[%d] %s (status=%d)\n", r->id, r->name, r->status);
+}
+
+int main(void) {
+    record_t r = { .id = 1, .name = "foo", .status = OK };
+    print_record(&r);
+    return 0;
+}

crates/kebab-chunk/tests/fixtures/sample.cpp

@@ -0,0 +1,40 @@
+#include <string>
+#include <vector>
+
+namespace kebab {
+namespace chunk {
+
+class MdHeadingV1Chunker {
+public:
+    MdHeadingV1Chunker() = default;
+    ~MdHeadingV1Chunker() = default;
+
+    std::string chunk_doc(const std::string& doc) {
+        return doc;
+    }
+
+    int operator()(int x) const {
+        return x * 2;
+    }
+
+private:
+    int counter_ = 0;
+};
+
+template <typename T>
+T identity(T value) {
+    return value;
+}
+
+}  // namespace chunk
+
+void global_helper() {
+    // free function in kebab namespace
+}
+
+}  // namespace kebab
+
+int main() {
+    kebab::chunk::MdHeadingV1Chunker c;
+    return 0;
+}

crates/kebab-chunk/tests/fixtures/sample_long_paragraph.txt

@@ -0,0 +1,200 @@
+line 001
+line 002
+line 003
+line 004
+line 005
+line 006
+line 007
+line 008
+line 009
+line 010
+line 011
+line 012
+line 013
+line 014
+line 015
+line 016
+line 017
+line 018
+line 019
+line 020
+line 021
+line 022
+line 023
+line 024
+line 025
+line 026
+line 027
+line 028
+line 029
+line 030
+line 031
+line 032
+line 033
+line 034
+line 035
+line 036
+line 037
+line 038
+line 039
+line 040
+line 041
+line 042
+line 043
+line 044
+line 045
+line 046
+line 047
+line 048
+line 049
+line 050
+line 051
+line 052
+line 053
+line 054
+line 055
+line 056
+line 057
+line 058
+line 059
+line 060
+line 061
+line 062
+line 063
+line 064
+line 065
+line 066
+line 067
+line 068
+line 069
+line 070
+line 071
+line 072
+line 073
+line 074
+line 075
+line 076
+line 077
+line 078
+line 079
+line 080
+line 081
+line 082
+line 083
+line 084
+line 085
+line 086
+line 087
+line 088
+line 089
+line 090
+line 091
+line 092
+line 093
+line 094
+line 095
+line 096
+line 097
+line 098
+line 099
+line 100
+line 101
+line 102
+line 103
+line 104
+line 105
+line 106
+line 107
+line 108
+line 109
+line 110
+line 111
+line 112
+line 113
+line 114
+line 115
+line 116
+line 117
+line 118
+line 119
+line 120
+line 121
+line 122
+line 123
+line 124
+line 125
+line 126
+line 127
+line 128
+line 129
+line 130
+line 131
+line 132
+line 133
+line 134
+line 135
+line 136
+line 137
+line 138
+line 139
+line 140
+line 141
+line 142
+line 143
+line 144
+line 145
+line 146
+line 147
+line 148
+line 149
+line 150
+line 151
+line 152
+line 153
+line 154
+line 155
+line 156
+line 157
+line 158
+line 159
+line 160
+line 161
+line 162
+line 163
+line 164
+line 165
+line 166
+line 167
+line 168
+line 169
+line 170
+line 171
+line 172
+line 173
+line 174
+line 175
+line 176
+line 177
+line 178
+line 179
+line 180
+line 181
+line 182
+line 183
+line 184
+line 185
+line 186
+line 187
+line 188
+line 189
+line 190
+line 191
+line 192
+line 193
+line 194
+line 195
+line 196
+line 197
+line 198
+line 199
+line 200

crates/kebab-chunk/tests/fixtures/sample_shell.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# First paragraph: env setup
+export KEBAB_HOME="${KEBAB_HOME:-$HOME/.local/share/kebab}"
+mkdir -p "$KEBAB_HOME"
+cd "$KEBAB_HOME"
+
+# Second paragraph: ingest
+echo "ingesting workspace..."
+kebab ingest --config /etc/kebab/config.toml
+
+# Third paragraph: report
+echo "done"
+kebab schema --json | jq '.stats'

crates/kebab-chunk/tests/k8s_manifest_resource_v1.rs

@@ -140,6 +140,17 @@ fn k8s_multi_doc_emits_one_chunk_per_resource() {
     for chunk in &chunks {
         assert_eq!(chunk.chunker_version.0, "k8s-manifest-resource-v1");
     }
+
+    // Every chunk from a multi-resource file must have a distinct chunk_id.
+    // Without the fix, all non-oversize resources get split_key=None which
+    // collapses to the same id_hash (= base_policy_hash) → UNIQUE constraint
+    // violation on the second resource.
+    let ids: std::collections::HashSet<_> = chunks.iter().map(|c| c.chunk_id.clone()).collect();
+    assert_eq!(
+        ids.len(),
+        chunks.len(),
+        "every k8s resource chunk must have a distinct chunk_id (multi-resource collision regression)"
+    );
 }
 
 /// A YAML document with an indentation error (tab in a space-indented context)
@@ -203,3 +214,73 @@ rules:
         other => panic!("expected Code span, got {other:?}"),
     }
 }
+
+/// 200+ line resource exercises `tier2_shared::push_chunks_with_oversize`'s
+/// line-window split branch. All chunks must share the same symbol
+/// (`<Kind>/<ns>/<name>`); their line ranges must form a contiguous
+/// partition; chunk_ids must all differ (the `#L{k}` suffix on `id_for_chunk`
+/// ensures uniqueness across windows). Spec p10-2 risks section explicitly
+/// flags "거대 ConfigMap" — this test covers that path.
+#[test]
+fn k8s_oversize_splits_into_line_windows_sharing_symbol() {
+    // ConfigMap with 250 data keys → ~256 total lines, > AST_CHUNK_MAX_LINES (200).
+    let mut yaml = String::from(
+        "apiVersion: v1\nkind: ConfigMap\nmetadata:\n  name: big\n  namespace: prod\ndata:\n",
+    );
+    for i in 0..250 {
+        yaml.push_str(&format!("  key{i}: value{i}\n"));
+    }
+
+    let doc = yaml_doc(&yaml);
+    let chunks = K8sManifestResourceV1Chunker
+        .chunk(&doc, &policy())
+        .expect("chunk");
+
+    assert!(
+        chunks.len() >= 2,
+        "expected ≥2 chunks for oversize resource, got {}",
+        chunks.len()
+    );
+
+    // Every chunk must share the same symbol + lang.
+    let expected_symbol = "ConfigMap/prod/big";
+    for (i, c) in chunks.iter().enumerate() {
+        match &c.source_spans[0] {
+            SourceSpan::Code { symbol, lang, .. } => {
+                assert_eq!(
+                    symbol.as_deref(),
+                    Some(expected_symbol),
+                    "chunk[{i}] symbol must equal `{expected_symbol}`"
+                );
+                assert_eq!(lang.as_deref(), Some("yaml"));
+            }
+            other => panic!("chunk[{i}]: expected Code span, got {other:?}"),
+        }
+    }
+
+    // chunk_ids must all be distinct (oversize fallback's #L{k} suffix).
+    let ids: std::collections::HashSet<_> = chunks.iter().map(|c| c.chunk_id.clone()).collect();
+    assert_eq!(
+        ids.len(),
+        chunks.len(),
+        "oversize chunks must have distinct chunk_ids (the #L{{k}} suffix should disambiguate)"
+    );
+
+    // Line ranges must form a contiguous partition: chunk[i].line_end + 1 == chunk[i+1].line_start.
+    let ranges: Vec<(u32, u32)> = chunks
+        .iter()
+        .map(|c| match &c.source_spans[0] {
+            SourceSpan::Code { line_start, line_end, .. } => (*line_start, *line_end),
+            other => panic!("expected Code span, got {other:?}"),
+        })
+        .collect();
+    for w in ranges.windows(2) {
+        let (_, prev_end) = w[0];
+        let (next_start, _) = w[1];
+        assert_eq!(
+            prev_end + 1,
+            next_start,
+            "line ranges must be contiguous: {prev_end} → {next_start} (got gap or overlap)"
+        );
+    }
+}

crates/kebab-chunk/tests/manifest_file_v1.rs

@@ -51,7 +51,7 @@ fn manifest_doc(lang: &str, manifest_text: &str) -> CanonicalDocument {
         doc_id,
         source_asset_id: aid,
         workspace_path: wp,
-        title: format!("Manifest ({})", lang),
+        title: format!("Manifest ({lang})"),
         lang: Lang("und".into()),
         blocks: vec![block],
         metadata: Metadata {

crates/kebab-cli/Cargo.toml

@@ -50,3 +50,6 @@ tempfile     = { workspace = true }
 # to simulate stale docs. `time` is the formatter used by the helper.
 rusqlite     = { workspace = true }
 time         = { workspace = true }
+
+[lints]
+workspace = true

crates/kebab-cli/src/main.rs

@@ -250,6 +250,18 @@ enum Cmd {
         /// `answer.v1`. Off by default to preserve final-only behavior.
         #[arg(long)]
         stream: bool,
+
+        /// p9-fb-41: route this ask through the multi-hop pipeline
+        /// — the query is decomposed into sub-questions, each
+        /// retrieved independently, then synthesized over the
+        /// merged chunk pool. Cost trade-off: 2–5× LLM calls
+        /// (decompose + 0..N decide + synthesize) vs. single-pass.
+        /// Worth it for compound questions (X 와 Y 의 관계, prereq
+        /// chain, cross-doc reasoning); single-pass is faster for
+        /// simple fact lookups. The full per-hop trace is exposed
+        /// on `Answer.hops` in `--json` mode.
+        #[arg(long)]
+        multi_hop: bool,
     },
 
     /// Wipe XDG data dirs (and optionally the Lance vector store) so the
@@ -785,7 +797,7 @@ fn run(cli: &Cli) -> anyhow::Result<()> {
                             serde_json::to_string(&item.query)?,
                         )?;
                         if let Some(err) = &item.error {
-                            writeln!(stdout, "error: {}", err)?;
+                            writeln!(stdout, "error: {err}")?;
                         } else if let Some(resp) = &item.response {
                             writeln!(
                                 stdout,
@@ -933,6 +945,15 @@ fn run(cli: &Cli) -> anyhow::Result<()> {
                     let next = resp.next_cursor.as_deref().unwrap_or("(none)");
                     eprintln!("[truncated; use --cursor {next} for the next page]");
                 }
+                // v0.17.0 A5 Step 4: short-query advisory. `resp.hint`
+                // is `Some` only when the result list is empty and the
+                // trimmed query is shorter than the trigram tokenizer
+                // can resolve (raw FTS5 mode opts out). stderr so it
+                // doesn't pollute the stdout hit list. `--json` skips
+                // this branch entirely; the field rides the wire.
+                if let Some(hint) = &resp.hint {
+                    eprintln!("[hint] {hint}");
+                }
                 if *trace {
                     if let Some(t) = &resp.trace {
                         eprintln!();
@@ -964,6 +985,7 @@ fn run(cli: &Cli) -> anyhow::Result<()> {
             hide_citations,
             session,
             stream,
+            multi_hop,
         } => {
             let cfg = kebab_config::Config::load(cli.config.as_deref())?;
             if *stream {
@@ -990,6 +1012,7 @@ fn run(cli: &Cli) -> anyhow::Result<()> {
                     history: Vec::new(),
                     conversation_id: None,
                     turn_index: None,
+                    multi_hop: *multi_hop,
                 };
                 let cfg2 = cfg.clone();
                 let q = query.clone();
@@ -1065,6 +1088,7 @@ fn run(cli: &Cli) -> anyhow::Result<()> {
                     history: Vec::new(),
                     conversation_id: None,
                     turn_index: None,
+                    multi_hop: *multi_hop,
                 };
                 let ans = match session.as_deref() {
                     Some(sid) => kebab_app::ask_with_session_with_config(cfg, sid, query, opts)?,
@@ -1147,15 +1171,13 @@ fn run(cli: &Cli) -> anyhow::Result<()> {
                 let report = kebab_app::reset::execute(scope, &cfg)?;
                 if cli.json {
                     println!("{}", serde_json::to_string(&wire::wire_reset(&report))?);
-                } else {
-                    if report.orphans_purged > 0 {
-                        println!("orphans purged: {}", report.orphans_purged);
-                        for p in &report.purged_paths {
-                            println!("  - {}", p.0);
-                        }
-                    } else {
-                        println!("no orphaned docs found — store is already in sync with walker scope");
+                } else if report.orphans_purged > 0 {
+                    println!("orphans purged: {}", report.orphans_purged);
+                    for p in &report.purged_paths {
+                        println!("  - {}", p.0);
                     }
+                } else {
+                    println!("no orphaned docs found — store is already in sync with walker scope");
                 }
                 return Ok(());
             }
@@ -1484,11 +1506,11 @@ fn confirm_destructive(
 ) -> anyhow::Result<bool> {
     use std::io::Write;
     let mut out = std::io::stderr().lock();
-    writeln!(out, "kebab reset ({:?}): about to remove", scope)?;
+    writeln!(out, "kebab reset ({scope:?}): about to remove")?;
     for p in paths {
         writeln!(out, "  - {}", p.display())?;
     }
-    writeln!(out, "estimated total: {} bytes", bytes)?;
+    writeln!(out, "estimated total: {bytes} bytes")?;
     write!(out, "Proceed? [y/N] ")?;
     out.flush()?;
 
@@ -1549,19 +1571,19 @@ fn render_fetch_plain(r: &kebab_core::FetchResult) {
             if !r.context_before.is_empty() {
                 println!("\n=== before ===");
                 for c in &r.context_before {
-                    let heading = c.heading_path.last().map(|s| s.as_str()).unwrap_or("");
+                    let heading = c.heading_path.last().map_or("", std::string::String::as_str);
                     println!("[{} § {}]\n{}\n", c.chunk_id.0, heading, c.text);
                 }
             }
             if let Some(c) = &r.chunk {
                 println!("\n=== target ===");
-                let heading = c.heading_path.last().map(|s| s.as_str()).unwrap_or("");
+                let heading = c.heading_path.last().map_or("", std::string::String::as_str);
                 println!("[{} § {}]\n{}\n", c.chunk_id.0, heading, c.text);
             }
             if !r.context_after.is_empty() {
                 println!("\n=== after ===");
                 for c in &r.context_after {
-                    let heading = c.heading_path.last().map(|s| s.as_str()).unwrap_or("");
+                    let heading = c.heading_path.last().map_or("", std::string::String::as_str);
                     println!("[{} § {}]\n{}\n", c.chunk_id.0, heading, c.text);
                 }
             }
@@ -1628,6 +1650,8 @@ mod tests {
             created_at: OffsetDateTime::now_utc(),
             conversation_id: None,
             turn_index: None,
+            hops: None,
+            verification: None,
         }
     }
 

crates/kebab-cli/src/wire.rs

@@ -92,6 +92,14 @@ pub fn wire_search_response(r: &kebab_app::SearchResponse) -> Value {
             map.insert("trace".to_string(), trace_v);
         }
     }
+    // v0.17.0 A5 Step 4b: emit `hint` only when set. Keeps responses
+    // that don't carry a hint backward-compatible with v0 consumers
+    // that don't know the field.
+    if let Some(hint) = &r.hint {
+        if let Value::Object(ref mut map) = v {
+            map.insert("hint".to_string(), Value::String(hint.clone()));
+        }
+    }
     tag_object(v, "search_response.v1")
 }
 
@@ -292,6 +300,7 @@ mod tests {
             next_cursor: Some("opaque-cursor-abc".to_string()),
             truncated: true,
             trace: None,
+            hint: None,
         };
         let v = wire_search_response(&r);
         assert_eq!(schema_of(&v), Some("search_response.v1"));
@@ -304,7 +313,7 @@ mod tests {
             v.get("next_cursor").and_then(|c| c.as_str()),
             Some("opaque-cursor-abc")
         );
-        assert_eq!(v.get("truncated").and_then(|t| t.as_bool()), Some(true));
+        assert_eq!(v.get("truncated").and_then(serde_json::Value::as_bool), Some(true));
     }
 
     #[test]
@@ -405,6 +414,7 @@ mod tests {
                 }],
                 timing: TraceTiming { lexical_ms: 5, vector_ms: 0, fusion_ms: 1, total_ms: 7 },
             }),
+            hint: None,
         };
         let v = wire_search_response(&r);
         assert_eq!(schema_of(&v), Some("search_response.v1"));
@@ -420,6 +430,7 @@ mod tests {
             next_cursor: None,
             truncated: false,
             trace: None,
+            hint: None,
         };
         let v = wire_search_response(&r);
         assert!(v.get("trace").is_none(), "trace field absent when None");

crates/kebab-cli/tests/cli_ingest_file.rs

@@ -88,5 +88,5 @@ max_context_tokens = 8000
     let stdout = String::from_utf8_lossy(&out.stdout);
     let v: serde_json::Value = serde_json::from_str(stdout.trim()).unwrap();
     assert_eq!(v.get("schema_version").and_then(|s| s.as_str()), Some("ingest_report.v1"));
-    assert_eq!(v.get("new").and_then(|n| n.as_u64()), Some(1));
+    assert_eq!(v.get("new").and_then(serde_json::Value::as_u64), Some(1));
 }

crates/kebab-cli/tests/cli_ingest_stdin.rs

@@ -96,5 +96,5 @@ max_context_tokens = 8000
     let stdout = String::from_utf8_lossy(&out.stdout);
     let v: serde_json::Value = serde_json::from_str(stdout.trim()).unwrap();
     assert_eq!(v.get("schema_version").and_then(|s| s.as_str()), Some("ingest_report.v1"));
-    assert_eq!(v.get("new").and_then(|n| n.as_u64()), Some(1));
+    assert_eq!(v.get("new").and_then(serde_json::Value::as_u64), Some(1));
 }

crates/kebab-cli/tests/cli_mcp_smoke.rs

@@ -43,7 +43,7 @@ fn cli_mcp_initialize_then_tools_list() {
     reader.read_line(&mut line).unwrap();
     let init: serde_json::Value = serde_json::from_str(line.trim()).unwrap();
     assert_eq!(
-        init.get("id").and_then(|i| i.as_i64()),
+        init.get("id").and_then(serde_json::Value::as_i64),
         Some(1),
         "unexpected id in initialize response: {init}"
     );
@@ -57,7 +57,7 @@ fn cli_mcp_initialize_then_tools_list() {
     reader.read_line(&mut line).unwrap();
     let list: serde_json::Value = serde_json::from_str(line.trim()).unwrap();
     assert_eq!(
-        list.get("id").and_then(|i| i.as_i64()),
+        list.get("id").and_then(serde_json::Value::as_i64),
         Some(2),
         "unexpected id in tools/list response: {list}"
     );

crates/kebab-cli/tests/cli_schema.rs

@@ -76,8 +76,7 @@ fn cli_schema_json_emits_schema_v1() {
     assert!(
         v.get("kebab_version")
             .and_then(|s| s.as_str())
-            .map(|s| !s.is_empty())
-            .unwrap_or(false),
+            .is_some_and(|s| !s.is_empty()),
         "kebab_version must be a non-empty string"
     );
 
@@ -86,12 +85,12 @@ fn cli_schema_json_emits_schema_v1() {
         .and_then(|c| c.as_object())
         .expect("capabilities must be a JSON object");
     assert_eq!(
-        caps.get("json_mode").and_then(|b| b.as_bool()),
+        caps.get("json_mode").and_then(serde_json::Value::as_bool),
         Some(true),
         "capabilities.json_mode must be true"
     );
     assert_eq!(
-        caps.get("mcp_server").and_then(|b| b.as_bool()),
+        caps.get("mcp_server").and_then(serde_json::Value::as_bool),
         Some(true),
         "capabilities.mcp_server must be true (fb-30)"
     );

crates/kebab-cli/tests/ingest_progress_cli.rs

@@ -155,8 +155,8 @@ fn ingest_json_progress_lines_carry_kind_and_ts() {
             saw_completed = true;
             // Counts mirror the report.
             let counts = v.get("counts").unwrap();
-            assert_eq!(counts.get("scanned").and_then(|n| n.as_u64()), Some(2));
-            assert_eq!(counts.get("new").and_then(|n| n.as_u64()), Some(2));
+            assert_eq!(counts.get("scanned").and_then(serde_json::Value::as_u64), Some(2));
+            assert_eq!(counts.get("new").and_then(serde_json::Value::as_u64), Some(2));
         }
     }
     assert!(saw_scan_started, "missing scan_started event");

crates/kebab-cli/tests/wire_ask_multi_hop.rs

@@ -0,0 +1,254 @@
+//! p9-fb-41 PR-4: CLI `--multi-hop` flag wiring + answer.v1 / error.v1
+//! schema additivity.
+//!
+//! Four Ollama-free pins:
+//!
+//! 1. `--multi-hop` is exposed on `kebab ask --help` so users can
+//!    discover the flag at the CLI surface (clap-level smoke).
+//! 2. `answer.schema.json` parses as valid JSON and declares a
+//!    `hops` property with a `HopRecord` `$defs` entry — guards
+//!    against accidental schema deletion / typo in future edits.
+//! 3. `answer.schema.json`'s `refusal_reason` enum lists
+//!    `multi_hop_decompose_failed` — agents validating against
+//!    the schema accept the new variant on refusal answers.
+//! 4. `error.schema.json`'s `code` enum lists
+//!    `multi_hop_decompose_failed` — forward-looking enum extension
+//!    documented in PR-4.
+//!
+//! End-to-end multi-hop ask against a live Ollama lands in a
+//! follow-up `#[ignore]` test (same pattern as `wire_ask_stale.rs`).
+
+use std::path::PathBuf;
+use std::process::Command;
+
+fn schema_path(name: &str) -> PathBuf {
+    PathBuf::from(env!("CARGO_MANIFEST_DIR"))
+        .join("..")
+        .join("..")
+        .join("docs")
+        .join("wire-schema")
+        .join("v1")
+        .join(name)
+}
+
+fn parse_schema(name: &str) -> serde_json::Value {
+    let text = std::fs::read_to_string(schema_path(name))
+        .unwrap_or_else(|e| panic!("read {name}: {e}"));
+    serde_json::from_str(&text)
+        .unwrap_or_else(|e| panic!("{name} must parse as valid JSON: {e}"))
+}
+
+#[test]
+fn cli_ask_help_advertises_multi_hop_flag() {
+    let bin = env!("CARGO_BIN_EXE_kebab");
+    let out = Command::new(bin).args(["ask", "--help"]).output().unwrap();
+    let stdout = String::from_utf8_lossy(&out.stdout);
+    assert!(
+        stdout.contains("--multi-hop"),
+        "`kebab ask --help` must advertise --multi-hop so users can discover it:\n{stdout}"
+    );
+}
+
+#[test]
+fn answer_schema_declares_hops_property_with_hop_record_defs() {
+    let schema = parse_schema("answer.schema.json");
+    assert!(
+        schema["properties"]["hops"].is_object(),
+        "`hops` property must be declared on answer.v1"
+    );
+    // `hops` allows array-or-null (single-pass omits the field;
+    // multi-hop emits a non-empty array).
+    let hops_any_of = schema["properties"]["hops"]["anyOf"]
+        .as_array()
+        .expect("hops must declare anyOf (array | null)");
+    assert!(
+        hops_any_of.iter().any(|v| v["type"] == "array"),
+        "hops anyOf must include array shape"
+    );
+    assert!(
+        hops_any_of.iter().any(|v| v["type"] == "null"),
+        "hops anyOf must include null (single-pass omits the field)"
+    );
+
+    // HopRecord $defs entry — guards against accidental deletion or
+    // structural drift in future schema edits.
+    let hop_record = &schema["$defs"]["HopRecord"];
+    assert!(
+        hop_record.is_object(),
+        "$defs.HopRecord must be declared so `hops.items` can $ref it"
+    );
+    let kind_enum = hop_record["properties"]["kind"]["enum"]
+        .as_array()
+        .expect("HopRecord.kind must be an enum");
+    let kinds: Vec<&str> = kind_enum.iter().filter_map(|v| v.as_str()).collect();
+    for needed in ["decompose", "decide", "synthesize"] {
+        assert!(
+            kinds.contains(&needed),
+            "HopRecord.kind enum must include {needed:?}, got {kinds:?}"
+        );
+    }
+}
+
+#[test]
+fn answer_schema_refusal_reason_enum_includes_multi_hop_decompose_failed() {
+    let schema = parse_schema("answer.schema.json");
+    let refusal_any_of = schema["properties"]["refusal_reason"]["anyOf"]
+        .as_array()
+        .expect("refusal_reason must declare anyOf");
+    let enum_arr = refusal_any_of
+        .iter()
+        .find_map(|v| v["enum"].as_array())
+        .expect("one of refusal_reason.anyOf entries must declare an enum");
+    let values: Vec<&str> = enum_arr.iter().filter_map(|v| v.as_str()).collect();
+    assert!(
+        values.contains(&"multi_hop_decompose_failed"),
+        "refusal_reason enum must include `multi_hop_decompose_failed`, got {values:?}"
+    );
+    // All earlier RefusalReason wire values remain on the enum —
+    // guards against an accidental rewrite dropping old variants.
+    for needed in [
+        "score_gate",
+        "llm_self_judge",
+        "no_index",
+        "no_chunks",
+        "llm_stream_aborted",
+    ] {
+        assert!(
+            values.contains(&needed),
+            "refusal_reason enum must keep prior variant {needed:?}, got {values:?}"
+        );
+    }
+}
+
+#[test]
+fn error_schema_code_enum_includes_multi_hop_decompose_failed() {
+    let schema = parse_schema("error.schema.json");
+    let code_enum = schema["properties"]["code"]["enum"]
+        .as_array()
+        .expect("error.v1 must declare code.enum");
+    let values: Vec<&str> = code_enum.iter().filter_map(|v| v.as_str()).collect();
+    assert!(
+        values.contains(&"multi_hop_decompose_failed"),
+        "error.v1 code enum must include forward-looking `multi_hop_decompose_failed`, got {values:?}"
+    );
+    // Existing codes remain — guards against accidental deletion.
+    for needed in [
+        "config_invalid",
+        "not_indexed",
+        "model_unreachable",
+        "generic",
+    ] {
+        assert!(
+            values.contains(&needed),
+            "error.v1 code enum must keep prior code {needed:?}, got {values:?}"
+        );
+    }
+}
+
+// ── p9-fb-41 PR-9c-1: NLI verification surface pins ─────────────────────
+
+/// answer.v1 must declare a `verification` property AND a
+/// `$defs.VerificationSummary` entry with all three required fields.
+/// Guards against accidental schema deletion / typo in future edits.
+#[test]
+fn answer_schema_declares_verification_field_and_defs() {
+    let schema = parse_schema("answer.schema.json");
+    assert!(
+        schema["properties"]["verification"].is_object(),
+        "`verification` property must be declared on answer.v1"
+    );
+    // `verification` allows object-or-null (multi-hop with threshold>0
+    // emits an object; everything else omits the field).
+    let v_any_of = schema["properties"]["verification"]["anyOf"]
+        .as_array()
+        .expect("verification must declare anyOf (object | null)");
+    assert!(
+        v_any_of.iter().any(|v| v["type"] == "null"),
+        "verification anyOf must include null (single-pass / disabled gate omits the field)"
+    );
+    assert!(
+        v_any_of
+            .iter()
+            .any(|v| v["$ref"].as_str() == Some("#/$defs/VerificationSummary")),
+        "verification anyOf must $ref VerificationSummary"
+    );
+
+    // VerificationSummary $defs entry + required fields.
+    let vs = &schema["$defs"]["VerificationSummary"];
+    assert!(
+        vs.is_object(),
+        "$defs.VerificationSummary must be declared so verification.anyOf can $ref it"
+    );
+    let required: Vec<&str> = vs["required"]
+        .as_array()
+        .expect("VerificationSummary.required must be an array")
+        .iter()
+        .filter_map(|v| v.as_str())
+        .collect();
+    for needed in ["nli_score", "nli_threshold", "nli_passed"] {
+        assert!(
+            required.contains(&needed),
+            "VerificationSummary.required must include {needed:?}, got {required:?}"
+        );
+    }
+}
+
+#[test]
+fn answer_schema_refusal_reason_enum_includes_nli_verification_failed() {
+    let schema = parse_schema("answer.schema.json");
+    let refusal_any_of = schema["properties"]["refusal_reason"]["anyOf"]
+        .as_array()
+        .expect("refusal_reason must declare anyOf");
+    let enum_arr = refusal_any_of
+        .iter()
+        .find_map(|v| v["enum"].as_array())
+        .expect("one of refusal_reason.anyOf entries must declare an enum");
+    let values: Vec<&str> = enum_arr.iter().filter_map(|v| v.as_str()).collect();
+    assert!(
+        values.contains(&"nli_verification_failed"),
+        "refusal_reason enum must include `nli_verification_failed`, got {values:?}"
+    );
+}
+
+#[test]
+fn answer_schema_refusal_reason_enum_includes_nli_model_unavailable() {
+    let schema = parse_schema("answer.schema.json");
+    let refusal_any_of = schema["properties"]["refusal_reason"]["anyOf"]
+        .as_array()
+        .expect("refusal_reason must declare anyOf");
+    let enum_arr = refusal_any_of
+        .iter()
+        .find_map(|v| v["enum"].as_array())
+        .expect("one of refusal_reason.anyOf entries must declare an enum");
+    let values: Vec<&str> = enum_arr.iter().filter_map(|v| v.as_str()).collect();
+    assert!(
+        values.contains(&"nli_model_unavailable"),
+        "refusal_reason enum must include `nli_model_unavailable`, got {values:?}"
+    );
+}
+
+#[test]
+fn error_schema_code_enum_includes_nli_verification_failed() {
+    let schema = parse_schema("error.schema.json");
+    let code_enum = schema["properties"]["code"]["enum"]
+        .as_array()
+        .expect("error.v1 must declare code.enum");
+    let values: Vec<&str> = code_enum.iter().filter_map(|v| v.as_str()).collect();
+    assert!(
+        values.contains(&"nli_verification_failed"),
+        "error.v1 code enum must include forward-looking `nli_verification_failed`, got {values:?}"
+    );
+}
+
+#[test]
+fn error_schema_code_enum_includes_nli_model_unavailable() {
+    let schema = parse_schema("error.schema.json");
+    let code_enum = schema["properties"]["code"]["enum"]
+        .as_array()
+        .expect("error.v1 must declare code.enum");
+    let values: Vec<&str> = code_enum.iter().filter_map(|v| v.as_str()).collect();
+    assert!(
+        values.contains(&"nli_model_unavailable"),
+        "error.v1 code enum must include forward-looking `nli_model_unavailable`, got {values:?}"
+    );
+}

crates/kebab-cli/tests/wire_search_response.rs

@@ -47,8 +47,20 @@ fn search_json_emits_search_response_v1_wrapper() {
 fn search_json_truncates_with_max_tokens() {
     let dir = tempfile::tempdir().unwrap();
     let (cfg, workspace, _data) = common::write_config(dir.path(), 30);
-    let body: String = "rust ownership is a memory model. ".repeat(10);
-    fs::write(workspace.join("a.md"), format!("# T\n\n{body}\n")).unwrap();
+    // v0.17.0 trigram tokenizer makes FTS5 snippet() tokens 3-char wide
+    // (was full words under unicode61), so an individual snippet stays
+    // around ~60 chars — too short to ever exceed the snippet-shorten
+    // budget cap on a single-hit fixture. To still exercise the budget
+    // loop deterministically, we ingest multiple hits and pick a budget
+    // small enough that the loop has to *pop* hits, which flips
+    // truncated=true regardless of snippet length.
+    for i in 0..5 {
+        fs::write(
+            workspace.join(format!("d{i}.md")),
+            format!("# T{i}\n\nrust ownership is a memory model.\n"),
+        )
+        .unwrap();
+    }
     common::ingest(&cfg, &workspace);
 
     let (stdout, _stderr) = common::run_search_with_args(
@@ -211,8 +223,15 @@ fn search_stale_cursor_returns_error_v1_with_stale_cursor_code() {
 fn search_plain_emits_truncated_hint_to_stderr() {
     let dir = tempfile::tempdir().unwrap();
     let (cfg, workspace, _data) = common::write_config(dir.path(), 30);
-    let body: String = "rust ownership is a memory model. ".repeat(10);
-    fs::write(workspace.join("a.md"), format!("# T\n\n{body}\n")).unwrap();
+    // v0.17.0 trigram tokenizer — same multi-doc rationale as
+    // `search_json_truncates_with_max_tokens` above.
+    for i in 0..5 {
+        fs::write(
+            workspace.join(format!("d{i}.md")),
+            format!("# T{i}\n\nrust ownership is a memory model.\n"),
+        )
+        .unwrap();
+    }
     common::ingest(&cfg, &workspace);
 
     let (_stdout, stderr) = common::run_search_with_args(
@@ -224,3 +243,76 @@ fn search_plain_emits_truncated_hint_to_stderr() {
         "stderr must carry truncated hint: {stderr:?}"
     );
 }
+
+#[test]
+fn search_plain_emits_short_query_hint_to_stderr() {
+    // v0.17.0 A5 Step 6: 2-char query under trigram tokenizer emits
+    // empty hits + stderr `[hint]` advisory. Empty workspace is enough
+    // — hits are always empty so the hint condition depends only on
+    // query length (<3 chars trimmed) + non-raw mode + hits.is_empty.
+    let dir = tempfile::tempdir().unwrap();
+    let (cfg, workspace, _data) = common::write_config(dir.path(), 30);
+    common::ingest(&cfg, &workspace);
+
+    let (_stdout, stderr) = common::run_search_with_args(
+        &cfg,
+        &["--mode", "lexical", "ab"],
+    );
+    assert!(
+        stderr.contains("[hint]"),
+        "stderr must carry short-query hint: {stderr:?}"
+    );
+    assert!(
+        stderr.contains("3자 이상"),
+        "hint message must mention '3자 이상' (Korean advisory): {stderr:?}"
+    );
+}
+
+#[test]
+fn search_json_emits_hint_field_for_short_query() {
+    // v0.17.0 A5 Step 6: --json mode carries the same advisory on the
+    // `search_response.v1.hint` additive field. Empty hits + 2-char
+    // query + non-raw mode trips the helper. Verifies the MCP-visible
+    // surface (agents read the field instead of parsing stderr).
+    let dir = tempfile::tempdir().unwrap();
+    let (cfg, workspace, _data) = common::write_config(dir.path(), 30);
+    common::ingest(&cfg, &workspace);
+
+    let (stdout, _stderr) = common::run_search_with_args(
+        &cfg,
+        &["--json", "--mode", "lexical", "ab"],
+    );
+    let v: Value = serde_json::from_str(stdout.trim())
+        .unwrap_or_else(|e| panic!("not JSON: {stdout:?}: {e}"));
+    assert!(
+        v["hits"].as_array().unwrap().is_empty(),
+        "empty hits expected for short query in empty KB: {v}"
+    );
+    assert_eq!(
+        v["hint"].as_str().expect("hint field set on short empty result"),
+        "3자 이상 키워드 권장 (trigram tokenizer 제약)",
+        "hint must carry the standard advisory: {v}"
+    );
+}
+
+#[test]
+fn search_json_omits_hint_field_when_query_is_long_enough() {
+    // v0.17.0 A5 Step 6 (negative case): 3+ char query never trips
+    // hint, even on an empty KB. Verifies `serialize_search_response`
+    // omits the additive `hint` field when `None` so existing wire
+    // consumers stay backward-compatible.
+    let dir = tempfile::tempdir().unwrap();
+    let (cfg, workspace, _data) = common::write_config(dir.path(), 30);
+    common::ingest(&cfg, &workspace);
+
+    let (stdout, _stderr) = common::run_search_with_args(
+        &cfg,
+        &["--json", "--mode", "lexical", "abc"],
+    );
+    let v: Value = serde_json::from_str(stdout.trim())
+        .unwrap_or_else(|e| panic!("not JSON: {stdout:?}: {e}"));
+    assert!(
+        v.get("hint").is_none(),
+        "hint must be absent for ≥3-char queries: {v}"
+    );
+}

crates/kebab-config/Cargo.toml

@@ -22,3 +22,6 @@ tracing      = { workspace = true }
 
 [dev-dependencies]
 tempfile     = { workspace = true }
+
+[lints]
+workspace = true

crates/kebab-config/src/lib.rs

@@ -103,6 +103,34 @@ pub struct ChunkingCfg {
 pub struct ModelsCfg {
     pub embedding: EmbeddingModelCfg,
     pub llm: LlmCfg,
+    /// p9-fb-41 PR-9c-1: NLI verifier model + provider knob.
+    /// `#[serde(default)]` so pre-v0.18 config files that predate the
+    /// `[models.nli]` section still load with built-in defaults
+    /// (`Xenova/mDeBERTa-v3-base-xnli-multilingual-nli-2mil7` / `onnx`).
+    /// The verifier itself is gated by `[rag].nli_threshold` — even
+    /// with a model configured here, threshold `0.0` (the default)
+    /// skips the verification step entirely.
+    #[serde(default = "NliCfg::defaults")]
+    pub nli: NliCfg,
+}
+
+/// p9-fb-41 PR-9c-1: NLI verifier configuration. The model id flows to
+/// `OnnxNliVerifier::new` via `kebab-nli` (PR-9c-2 wiring); the provider
+/// is reserved for future verifier swap-in (currently only `"onnx"` is
+/// recognized — anything else falls back to the same path).
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+pub struct NliCfg {
+    pub model: String,
+    pub provider: String,
+}
+
+impl NliCfg {
+    pub fn defaults() -> Self {
+        Self {
+            model: "Xenova/mDeBERTa-v3-base-xnli-multilingual-nli-2mil7".to_string(),
+            provider: "onnx".to_string(),
+        }
+    }
 }
 
 #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
@@ -122,6 +150,23 @@ pub struct LlmCfg {
     pub endpoint: String,
     pub temperature: f32,
     pub seed: u64,
+    /// v0.17.0 post-dogfood: Hard ceiling on a single HTTP exchange to
+    /// the LLM endpoint (Ollama, etc.). Cold-loading an 8B+ model on
+    /// CPU-only hosts can spend 60-90s on model load + several minutes
+    /// on a first inference, blowing past the old hard-coded 300s cap
+    /// and surfacing as `error: kb-rag: llm.generate_stream` to the
+    /// user. Config-driven so 16-GB / CPU-only deployments using small
+    /// (≤4B) models can keep the original 300s and large-model dogfood
+    /// can dial it up (e.g. 1200s) without rebuilding.
+    ///
+    /// **Edge case — `0` is NOT a disable sentinel.**
+    /// `reqwest::ClientBuilder::timeout(Duration::from_secs(0))` sets a
+    /// 0-second read timeout, so every request fails *immediately* with
+    /// `error: kb-rag: ollama timeout`. To approximate "no cap", use a
+    /// large finite value (e.g. `u64::MAX` ≈ 5.8 × 10¹¹ years, or
+    /// just a generous number like `86400`).
+    #[serde(default = "default_llm_request_timeout_secs")]
+    pub request_timeout_secs: u64,
 }
 
 #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
@@ -147,6 +192,13 @@ fn default_cache_capacity() -> usize {
     256
 }
 
+/// v0.17.0 post-dogfood: matches the legacy hard-coded ceiling so
+/// existing configs that omit the field keep behaving identically.
+/// Overridable per config / `KEBAB_MODELS_LLM_REQUEST_TIMEOUT_SECS`.
+fn default_llm_request_timeout_secs() -> u64 {
+    300
+}
+
 fn default_stale_threshold_days() -> u32 {
     30
 }
@@ -157,6 +209,73 @@ pub struct RagCfg {
     pub score_gate: f32,
     pub explain_default: bool,
     pub max_context_tokens: usize,
+    /// p9-fb-41: hard ceiling on the number of multi-hop iterations
+    /// (decompose iter + decide iters). When the LLM keeps returning
+    /// `continue` past this depth the pipeline cuts to `synthesize`
+    /// with `HopRecord.forced_stop = true`. Default `3` — enough for
+    /// most cross-doc reasoning, low enough to bound LLM cost.
+    #[serde(default = "default_multi_hop_max_depth")]
+    pub multi_hop_max_depth: u32,
+    /// p9-fb-41: cap on how many sub-queries the LLM may emit in a
+    /// single decompose / decide call. This is the *prompt-side
+    /// soft hint* — the value the pipeline injects into the
+    /// decompose / decide prompts so the LLM knows what to aim for.
+    /// kebab-rag enforces a separate compile-time hard ceiling
+    /// (`MULTI_HOP_MAX_SUB_QUERIES_HARD_CAP`, currently 10) as a
+    /// safety net against misbehaving models — if you raise this
+    /// knob above the hard cap, bump the const in the same PR.
+    /// Default `5`.
+    #[serde(default = "default_multi_hop_max_sub_queries_per_iter")]
+    pub multi_hop_max_sub_queries_per_iter: u32,
+    /// p9-fb-41: hard ceiling on the deduped chunk pool. When the
+    /// accumulated pool would exceed this many chunks the pipeline
+    /// stops accepting new retrieval results and forces synthesize
+    /// with `forced_stop = true`.
+    ///
+    /// Default `15` — tuned down from the original 30 in the v0.18
+    /// pre-cut dogfood (`tasks/HOTFIXES.md` 2026-05-25 fb-41 entry,
+    /// "post-PR-7 dogfood retest + PR-8 partial mitigation" sub-section).
+    /// With 30 chunks the synthesize prompt was large enough for
+    /// gemma3:4b to lose the citation rule + drift into unrelated
+    /// chunks; 15 keeps the prompt tight while still allowing 3-iter
+    /// cross-doc reasoning over ~5 chunks per iter.
+    #[serde(default = "default_multi_hop_max_pool_chunks")]
+    pub multi_hop_max_pool_chunks: u32,
+    /// p9-fb-41 PR-9c-1: minimum NLI entailment score required for the
+    /// multi-hop synthesize answer to be returned as `grounded=true`
+    /// (spec §2.6 single gate). When the post-synthesize NLI verifier
+    /// returns `NliScores::faithfulness() < nli_threshold` the
+    /// pipeline refuses with `RefusalReason::NliVerificationFailed`.
+    ///
+    /// Default `0.0` = verification disabled — no NLI call, multi-hop
+    /// matches its PR-3b behavior exactly. Set to e.g. `0.5` to
+    /// activate the gate. Knob lives on `[rag]` (the gate is a RAG
+    /// policy, not a model property); the model itself comes from
+    /// `[models.nli].model`.
+    ///
+    /// Single-pass `ask` ignores this knob entirely — only multi-hop
+    /// runs through the verification step (PR-9c-2 wires it).
+    #[serde(default = "default_nli_threshold")]
+    pub nli_threshold: f32,
+}
+
+fn default_multi_hop_max_depth() -> u32 {
+    3
+}
+
+fn default_multi_hop_max_sub_queries_per_iter() -> u32 {
+    5
+}
+
+fn default_multi_hop_max_pool_chunks() -> u32 {
+    15
+}
+
+/// p9-fb-41 PR-9c-1: NLI gate disabled by default per spec §2.6
+/// (verification opt-in — users explicitly raise the threshold once
+/// they're ready to trade refusal-rate for groundedness).
+fn default_nli_threshold() -> f32 {
+    0.0
 }
 
 /// Settings for the image ingest pipeline (P6). `ocr` controls OCR
@@ -204,6 +323,22 @@ pub struct OcrCfg {
     /// Cap the long edge of the image (in pixels) before sending. Larger
     /// images bloat prompt cost. Default `1600`.
     pub max_pixels: u32,
+    /// v0.17.2 post-dogfood: Hard ceiling on a single HTTP exchange to
+    /// the OCR endpoint. Sister knob to [`LlmCfg::request_timeout_secs`]
+    /// — kept separate because OCR latency is typically shorter than
+    /// chat-LLM cold start, and large vision models on CPU-only hosts
+    /// occasionally need a different budget. See HOTFIXES 2026-05-25
+    /// for the rationale.
+    ///
+    /// **Edge case — `0` is NOT a disable sentinel.** Same semantics as
+    /// [`LlmCfg::request_timeout_secs`]: `Duration::from_secs(0)` means
+    /// "every request fails immediately" (reqwest 0.12.x — the read
+    /// timeout is applied as a 0-second deadline), not "no timeout".
+    /// To approximate "no cap", use a large finite value (e.g.
+    /// `u64::MAX` ≈ 5.8 × 10¹¹ years, or just a generous number like
+    /// `86400`).
+    #[serde(default = "default_ocr_request_timeout_secs")]
+    pub request_timeout_secs: u64,
 }
 
 impl OcrCfg {
@@ -215,10 +350,18 @@ impl OcrCfg {
             endpoint: None,
             languages: vec!["eng".to_string(), "kor".to_string()],
             max_pixels: 1600,
+            request_timeout_secs: default_ocr_request_timeout_secs(),
         }
     }
 }
 
+/// 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`.
+fn default_ocr_request_timeout_secs() -> u64 {
+    300
+}
+
 /// Caption settings (P6-3). Caption uses the same Ollama-vision /
 /// `LanguageModel` pipeline as the rest of the workspace; the trait
 /// abstraction is the part the spec demands. `enabled` defaults to
@@ -363,13 +506,16 @@ impl Config {
                     // gemma4 계열 통일 — OCR (P6-2) + caption (P6-3)
                     // 어댑터가 같은 family 사용. 사용자가 더 큰
                     // variant (gemma4:26b 등) 원하면 자기 config.toml
-                    // 에서 override.
+                    // 에서 override. CPU-only / ≤16 GB RAM 환경이면
+                    // gemma3:4b 같은 ≤4B Q4 모델 권장 (README 참조).
                     model: "gemma4:e4b".to_string(),
                     context_tokens: 32768,
                     endpoint: "http://127.0.0.1:11434".to_string(),
                     temperature: 0.0,
                     seed: 0,
+                    request_timeout_secs: default_llm_request_timeout_secs(),
                 },
+                nli: NliCfg::defaults(),
             },
             search: SearchCfg {
                 default_k: 10,
@@ -384,6 +530,11 @@ impl Config {
                 score_gate: 0.30,
                 explain_default: false,
                 max_context_tokens: 8000,
+                multi_hop_max_depth: default_multi_hop_max_depth(),
+                multi_hop_max_sub_queries_per_iter:
+                    default_multi_hop_max_sub_queries_per_iter(),
+                multi_hop_max_pool_chunks: default_multi_hop_max_pool_chunks(),
+                nli_threshold: default_nli_threshold(),
             },
             image: ImageCfg::defaults(),
             ui: UiCfg::defaults(),
@@ -621,6 +772,15 @@ impl Config {
                         self.models.llm.seed = n;
                     }
                 }
+                "KEBAB_MODELS_LLM_REQUEST_TIMEOUT_SECS" => {
+                    if let Ok(n) = v.parse::<u64>() {
+                        self.models.llm.request_timeout_secs = n;
+                    }
+                }
+
+                // models.nli (p9-fb-41 PR-9c-1)
+                "KEBAB_MODELS_NLI_MODEL" => self.models.nli.model = v.clone(),
+                "KEBAB_MODELS_NLI_PROVIDER" => self.models.nli.provider = v.clone(),
 
                 // search
                 "KEBAB_SEARCH_DEFAULT_K" => {
@@ -662,6 +822,39 @@ impl Config {
                         self.rag.max_context_tokens = n;
                     }
                 }
+                "KEBAB_RAG_MULTI_HOP_MAX_DEPTH" => {
+                    if let Ok(n) = v.parse::<u32>() {
+                        self.rag.multi_hop_max_depth = n;
+                    }
+                }
+                "KEBAB_RAG_MULTI_HOP_MAX_SUB_QUERIES_PER_ITER" => {
+                    if let Ok(n) = v.parse::<u32>() {
+                        self.rag.multi_hop_max_sub_queries_per_iter = n;
+                    }
+                }
+                "KEBAB_RAG_MULTI_HOP_MAX_POOL_CHUNKS" => {
+                    if let Ok(n) = v.parse::<u32>() {
+                        self.rag.multi_hop_max_pool_chunks = n;
+                    }
+                }
+                // p9-fb-41 PR-9c-1: NLI gate threshold. Parse failure
+                // emits a `tracing::warn!` (not silent like the other
+                // numeric env overrides) because this knob gates the
+                // NLI verification entirely — a malformed env value
+                // would silently disable a security-flavored gate the
+                // user thought they enabled, which is the failure mode
+                // most worth surfacing. The default (`0.0`) survives
+                // on parse failure so behaviour stays well-defined.
+                "KEBAB_RAG_NLI_THRESHOLD" => match v.parse::<f32>() {
+                    Ok(f) => self.rag.nli_threshold = f,
+                    Err(e) => tracing::warn!(
+                        target: "kebab-config",
+                        env_key = "KEBAB_RAG_NLI_THRESHOLD",
+                        env_value = %v,
+                        error = %e,
+                        "invalid KEBAB_RAG_NLI_THRESHOLD; keeping prior value (0.0 = NLI gate disabled)"
+                    ),
+                },
 
                 // image.ocr
                 "KEBAB_IMAGE_OCR_ENABLED" => {
@@ -691,6 +884,11 @@ impl Config {
                         self.image.ocr.max_pixels = n;
                     }
                 }
+                "KEBAB_IMAGE_OCR_REQUEST_TIMEOUT_SECS" => {
+                    if let Ok(n) = v.parse::<u64>() {
+                        self.image.ocr.request_timeout_secs = n;
+                    }
+                }
 
                 // image.caption (P6-3)
                 "KEBAB_IMAGE_CAPTION_ENABLED" => {
@@ -803,6 +1001,83 @@ fn parse_bool(s: &str) -> bool {
 mod tests {
     use super::*;
 
+    /// Legacy TOML fixture written before the `request_timeout_secs`
+    /// knobs (LLM in v0.17.1, OCR follow-up) existed. Shared by
+    /// `legacy_config_without_request_timeout_secs_uses_default`
+    /// (LLM-side) and `legacy_config_without_ocr_request_timeout_secs_uses_default`
+    /// (OCR-side) so both invariants pin against the same on-disk
+    /// shape — schema drift in the legacy form only needs one edit.
+    const LEGACY_PRE_TIMEOUT_TOML: &str = r#"
+schema_version = 1
+
+[workspace]
+root = "/tmp/x"
+exclude = []
+
+[storage]
+data_dir = "/tmp/x"
+sqlite = "/tmp/x/kebab.sqlite"
+vector_dir = "/tmp/x/lancedb"
+asset_dir = "/tmp/x/assets"
+artifact_dir = "/tmp/x/artifacts"
+model_dir = "/tmp/x/models"
+runs_dir = "/tmp/x/runs"
+copy_threshold_mb = 100
+
+[indexing]
+max_parallel_extractors = 2
+max_parallel_embeddings = 1
+watch_filesystem = false
+
+[chunking]
+target_tokens = 500
+overlap_tokens = 80
+respect_markdown_headings = true
+chunker_version = "md-heading-v1"
+
+[models.embedding]
+provider = "fastembed"
+model = "multilingual-e5-large"
+version = "v1"
+dimensions = 1024
+batch_size = 64
+
+[models.llm]
+provider = "ollama"
+model = "gemma3:4b"
+context_tokens = 4096
+endpoint = "http://127.0.0.1:11434"
+temperature = 0.0
+seed = 0
+
+[search]
+default_k = 10
+hybrid_fusion = "rrf"
+rrf_k = 60
+snippet_chars = 220
+
+[rag]
+prompt_template_version = "rag-v2"
+score_gate = 0.3
+explain_default = false
+max_context_tokens = 8000
+
+[image.ocr]
+enabled = false
+engine = "ollama-vision"
+model = "gemma3:4b"
+languages = ["eng"]
+max_pixels = 1600
+
+[image.caption]
+enabled = false
+max_pixels = 768
+prompt_template_version = "caption-v1"
+
+[ui]
+theme = "dark"
+"#;
+
     #[test]
     fn defaults_are_serde_roundtrip_stable() {
         let c = Config::defaults();
@@ -873,6 +1148,35 @@ mod tests {
         assert!((c.models.llm.temperature - 0.7).abs() < 1e-6);
     }
 
+    /// v0.17.0 post-dogfood: matches the legacy hard-coded 300s cap so
+    /// existing configs that omit the new field are not affected.
+    #[test]
+    fn default_llm_request_timeout_secs_is_300() {
+        assert_eq!(Config::defaults().models.llm.request_timeout_secs, 300);
+    }
+
+    #[test]
+    fn env_overrides_models_llm_request_timeout_secs() {
+        let mut env = HashMap::new();
+        env.insert(
+            "KEBAB_MODELS_LLM_REQUEST_TIMEOUT_SECS".to_string(),
+            "1200".to_string(),
+        );
+        let c = Config::defaults().apply_env(&env);
+        assert_eq!(c.models.llm.request_timeout_secs, 1200);
+    }
+
+    /// v0.17.0 post-dogfood: a config file written before the field
+    /// existed (no `request_timeout_secs` key) must still parse and fall
+    /// back to the 300s default — backwards-compat invariant. Fixture
+    /// shared with the OCR-side invariant via [`LEGACY_PRE_TIMEOUT_TOML`].
+    #[test]
+    fn legacy_config_without_request_timeout_secs_uses_default() {
+        let c: Config = toml::from_str(LEGACY_PRE_TIMEOUT_TOML)
+            .expect("parse legacy config");
+        assert_eq!(c.models.llm.request_timeout_secs, 300);
+    }
+
     #[test]
     fn env_overrides_indexing_watch_filesystem_bool() {
         let mut env = HashMap::new();
@@ -894,6 +1198,175 @@ mod tests {
         assert_eq!(c.image.ocr.max_pixels, 1600);
     }
 
+    /// v0.17.2 post-dogfood: matches the legacy hard-coded 300s cap so
+    /// existing configs that omit the new field keep behaving identically.
+    #[test]
+    fn default_ocr_request_timeout_secs_is_300() {
+        assert_eq!(
+            Config::defaults().image.ocr.request_timeout_secs,
+            300
+        );
+    }
+
+    #[test]
+    fn env_overrides_image_ocr_request_timeout_secs() {
+        let mut env = HashMap::new();
+        env.insert(
+            "KEBAB_IMAGE_OCR_REQUEST_TIMEOUT_SECS".to_string(),
+            "900".to_string(),
+        );
+        let c = Config::defaults().apply_env(&env);
+        assert_eq!(c.image.ocr.request_timeout_secs, 900);
+    }
+
+    /// post-v0.17.1 dogfood: a config file written before the OCR
+    /// timeout field existed must still parse and fall back to the
+    /// 300s default — backwards-compat invariant. Fixture shared
+    /// with the LLM-side invariant via [`LEGACY_PRE_TIMEOUT_TOML`].
+    #[test]
+    fn legacy_config_without_ocr_request_timeout_secs_uses_default() {
+        let c: Config = toml::from_str(LEGACY_PRE_TIMEOUT_TOML)
+            .expect("parse legacy config");
+        assert_eq!(c.image.ocr.request_timeout_secs, 300);
+    }
+
+    // ── p9-fb-41: multi-hop RAG knobs ────────────────────────────────────
+
+    #[test]
+    fn default_multi_hop_max_depth_is_3() {
+        assert_eq!(Config::defaults().rag.multi_hop_max_depth, 3);
+    }
+
+    #[test]
+    fn default_multi_hop_max_sub_queries_per_iter_is_5() {
+        assert_eq!(
+            Config::defaults().rag.multi_hop_max_sub_queries_per_iter,
+            5
+        );
+    }
+
+    #[test]
+    fn default_multi_hop_max_pool_chunks_is_15() {
+        // v0.18 dogfood (HOTFIXES 2026-05-25 fb-41 post-PR-7) tuned
+        // this down from 30 → 15 to keep the synthesize prompt tight
+        // enough for gemma3:4b to follow the citation rule.
+        assert_eq!(Config::defaults().rag.multi_hop_max_pool_chunks, 15);
+    }
+
+    #[test]
+    fn env_overrides_multi_hop_knobs() {
+        let mut env = HashMap::new();
+        env.insert(
+            "KEBAB_RAG_MULTI_HOP_MAX_DEPTH".to_string(),
+            "5".to_string(),
+        );
+        env.insert(
+            "KEBAB_RAG_MULTI_HOP_MAX_SUB_QUERIES_PER_ITER".to_string(),
+            "7".to_string(),
+        );
+        env.insert(
+            "KEBAB_RAG_MULTI_HOP_MAX_POOL_CHUNKS".to_string(),
+            "50".to_string(),
+        );
+        let c = Config::defaults().apply_env(&env);
+        assert_eq!(c.rag.multi_hop_max_depth, 5);
+        assert_eq!(c.rag.multi_hop_max_sub_queries_per_iter, 7);
+        assert_eq!(c.rag.multi_hop_max_pool_chunks, 50);
+    }
+
+    /// post-PR-3 fb-41: a config file written before the multi-hop
+    /// knobs existed must still parse and fall back to the documented
+    /// defaults — backwards-compat invariant. Fixture shared with the
+    /// LLM / OCR timeout invariants via [`LEGACY_PRE_TIMEOUT_TOML`]
+    /// (that fixture also predates the multi_hop_* fields).
+    #[test]
+    fn legacy_config_without_multi_hop_knobs_uses_defaults() {
+        let c: Config = toml::from_str(LEGACY_PRE_TIMEOUT_TOML)
+            .expect("parse legacy config");
+        assert_eq!(c.rag.multi_hop_max_depth, 3);
+        assert_eq!(c.rag.multi_hop_max_sub_queries_per_iter, 5);
+        // v0.18 dogfood (post-PR-7): pool default 30 → 15.
+        assert_eq!(c.rag.multi_hop_max_pool_chunks, 15);
+    }
+
+    // ── p9-fb-41 PR-9c-1: NLI verification knobs ─────────────────────────
+
+    #[test]
+    fn default_nli_threshold_is_zero() {
+        // Spec §2.6: NLI gate disabled by default — verification is
+        // opt-in. `0.0` keeps multi-hop behavior identical to PR-3b.
+        assert_eq!(Config::defaults().rag.nli_threshold, 0.0);
+    }
+
+    #[test]
+    fn default_nli_model_is_xenova_mdeberta() {
+        // Pin the default model id so a refactor that touches NliCfg
+        // can't silently flip to a different verifier model.
+        assert_eq!(
+            Config::defaults().models.nli.model,
+            "Xenova/mDeBERTa-v3-base-xnli-multilingual-nli-2mil7"
+        );
+        assert_eq!(Config::defaults().models.nli.provider, "onnx");
+    }
+
+    /// A config file written before the `[models.nli]` / `nli_threshold`
+    /// keys existed must still parse and fall back to the documented
+    /// defaults. Fixture shared via [`LEGACY_PRE_TIMEOUT_TOML`] (predates
+    /// all PR-9c-1 fields).
+    #[test]
+    fn legacy_config_without_nli_uses_defaults() {
+        let c: Config = toml::from_str(LEGACY_PRE_TIMEOUT_TOML)
+            .expect("parse legacy config");
+        assert_eq!(c.rag.nli_threshold, 0.0);
+        assert_eq!(
+            c.models.nli.model,
+            "Xenova/mDeBERTa-v3-base-xnli-multilingual-nli-2mil7"
+        );
+        assert_eq!(c.models.nli.provider, "onnx");
+    }
+
+    #[test]
+    fn env_override_nli_threshold() {
+        let mut env = HashMap::new();
+        env.insert("KEBAB_RAG_NLI_THRESHOLD".to_string(), "0.5".to_string());
+        let c = Config::defaults().apply_env(&env);
+        assert!((c.rag.nli_threshold - 0.5).abs() < 1e-6);
+    }
+
+    #[test]
+    fn env_override_nli_model_and_provider() {
+        let mut env = HashMap::new();
+        env.insert(
+            "KEBAB_MODELS_NLI_MODEL".to_string(),
+            "user/custom-nli-model".to_string(),
+        );
+        env.insert(
+            "KEBAB_MODELS_NLI_PROVIDER".to_string(),
+            "candle".to_string(),
+        );
+        let c = Config::defaults().apply_env(&env);
+        assert_eq!(c.models.nli.model, "user/custom-nli-model");
+        assert_eq!(c.models.nli.provider, "candle");
+    }
+
+    /// Malformed `KEBAB_RAG_NLI_THRESHOLD` keeps the prior value (does
+    /// NOT silently disable nor crash). The `tracing::warn!` surface
+    /// is observable only when the user has tracing wired; the
+    /// behavior contract is "default survives".
+    #[test]
+    fn env_malformed_nli_threshold_keeps_prior_value() {
+        let mut env = HashMap::new();
+        env.insert(
+            "KEBAB_RAG_NLI_THRESHOLD".to_string(),
+            "not-a-float".to_string(),
+        );
+        let c = Config::defaults().apply_env(&env);
+        assert_eq!(
+            c.rag.nli_threshold, 0.0,
+            "malformed env value must keep the default unchanged"
+        );
+    }
+
     #[test]
     fn image_ocr_env_overrides() {
         let mut env = HashMap::new();

crates/kebab-config/src/paths.rs

@@ -157,7 +157,7 @@ mod tests {
 
     #[test]
     fn xdg_data_home_set_replaces_var() {
-        let _lock = ENV_LOCK.lock().unwrap_or_else(|p| p.into_inner());
+        let _lock = ENV_LOCK.lock().unwrap_or_else(std::sync::PoisonError::into_inner);
         let _guard = XdgGuard::capture();
         // SAFETY: lock held for the duration of this test.
         unsafe { std::env::set_var("XDG_DATA_HOME", "/custom/path") };
@@ -168,7 +168,7 @@ mod tests {
 
     #[test]
     fn xdg_data_home_unset_uses_default() {
-        let _lock = ENV_LOCK.lock().unwrap_or_else(|p| p.into_inner());
+        let _lock = ENV_LOCK.lock().unwrap_or_else(std::sync::PoisonError::into_inner);
         let _guard = XdgGuard::capture();
         // SAFETY: lock held for the duration of this test.
         unsafe { std::env::remove_var("XDG_DATA_HOME") };
@@ -181,7 +181,7 @@ mod tests {
 
     #[test]
     fn xdg_with_no_default_resolves_to_empty_when_unset() {
-        let _lock = ENV_LOCK.lock().unwrap_or_else(|p| p.into_inner());
+        let _lock = ENV_LOCK.lock().unwrap_or_else(std::sync::PoisonError::into_inner);
         let _guard = XdgGuard::capture();
         // SAFETY: lock held for the duration of this test.
         unsafe { std::env::remove_var("XDG_DATA_HOME") };
@@ -193,7 +193,7 @@ mod tests {
 
     #[test]
     fn leading_tilde_expands_to_home() {
-        let _lock = ENV_LOCK.lock().unwrap_or_else(|p| p.into_inner());
+        let _lock = ENV_LOCK.lock().unwrap_or_else(std::sync::PoisonError::into_inner);
         let home = std::env::var("HOME").expect("HOME must be set in tests");
         let p = expand_path("~/runs", "");
         assert_eq!(p, PathBuf::from(home).join("runs"));
@@ -229,7 +229,7 @@ mod tests {
 
     #[test]
     fn tilde_path_ignores_base_dir() {
-        let _lock = ENV_LOCK.lock().unwrap_or_else(|p| p.into_inner());
+        let _lock = ENV_LOCK.lock().unwrap_or_else(std::sync::PoisonError::into_inner);
         let home = std::env::var("HOME").expect("HOME must be set in tests");
         let base = Path::new("/tmp/ignored-cfg");
         let p = expand_path_with_base("~/x", "", base);
@@ -238,7 +238,7 @@ mod tests {
 
     #[test]
     fn xdg_var_path_ignores_base_dir() {
-        let _lock = ENV_LOCK.lock().unwrap_or_else(|p| p.into_inner());
+        let _lock = ENV_LOCK.lock().unwrap_or_else(std::sync::PoisonError::into_inner);
         let _guard = XdgGuard::capture();
         // SAFETY: lock held for the duration of this test.
         unsafe { std::env::set_var("XDG_DATA_HOME", "/xdg/data") };
@@ -255,7 +255,7 @@ mod tests {
         // Order matters: substitute `{data_dir}` (which itself contains
         // an unexpanded `${XDG_DATA_HOME}` and `~`), then the other two
         // resolve the result.
-        let _lock = ENV_LOCK.lock().unwrap_or_else(|p| p.into_inner());
+        let _lock = ENV_LOCK.lock().unwrap_or_else(std::sync::PoisonError::into_inner);
         let _guard = XdgGuard::capture();
         // SAFETY: lock held for the duration of this test.
         unsafe { std::env::set_var("XDG_DATA_HOME", "/xdg/data") };

crates/kebab-core/Cargo.toml

@@ -16,3 +16,6 @@ time                      = { workspace = true }
 blake3                    = { workspace = true }
 serde_json_canonicalizer  = "0.3"
 unicode-normalization     = "0.1"
+
+[lints]
+workspace = true

crates/kebab-core/src/answer.rs

@@ -29,6 +29,37 @@ pub struct Answer {
     /// 이면 single-shot.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub turn_index: Option<u32>,
+    /// p9-fb-41: multi-hop hop trace. `None` for single-pass asks.
+    /// Each entry records one hop (`decompose` / `decide` / `synthesize`)
+    /// — the LLM call category, the sub-queries emitted, retrieval
+    /// counts, and a `forced_stop` flag for cap-driven termination.
+    /// Wire-additive: `answer.v1` schema_version unchanged; consumers
+    /// reading older single-pass answers see `hops: None` (or absent).
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub hops: Option<Vec<HopRecord>>,
+    /// p9-fb-41 PR-9c-1: NLI-based post-synthesis verification summary.
+    /// `None` for single-pass asks and for multi-hop runs with
+    /// `[rag].nli_threshold == 0` (verification disabled — the default).
+    /// Present only when the multi-hop pipeline reached the post-
+    /// synthesize verification step (PR-9c-2 wires step 8.5). Wire-
+    /// additive: `answer.v1` schema_version unchanged; consumers
+    /// reading pre-v0.18 answers see `verification: None` (or absent).
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub verification: Option<VerificationSummary>,
+}
+
+/// p9-fb-41 PR-9c-1: post-synthesize NLI verification summary stamped
+/// onto [`Answer::verification`] when multi-hop runs reach step 8.5
+/// (NLI gate). Three required fields ride together on every wire emit:
+/// `nli_score` is the entailment channel of the XNLI verifier,
+/// `nli_threshold` mirrors `[rag].nli_threshold` for audit, and
+/// `nli_passed` is `nli_score >= nli_threshold`. The whole struct is
+/// omitted (serde skip) when no verification ran.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Serialize, Deserialize)]
+pub struct VerificationSummary {
+    pub nli_score: f32,
+    pub nli_threshold: f32,
+    pub nli_passed: bool,
 }
 
 #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
@@ -55,6 +86,79 @@ pub struct Turn {
     pub created_at: OffsetDateTime,
 }
 
+/// p9-fb-41: one entry in [`Answer::hops`] — the per-iteration trace
+/// of a multi-hop ask. The pipeline appends a `HopRecord` per LLM
+/// call (decompose / decide / synthesize) so a `--multi-hop` user
+/// can see what sub-queries the LLM emitted, how many chunks each
+/// hop contributed, whether the iter stopped on the model's own
+/// signal or hit a cap, and the per-hop LLM latency.
+///
+/// Wire-additive — every field uses `#[serde(default)]` where it
+/// could plausibly be omitted by a future schema reader.
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+pub struct HopRecord {
+    /// 0-based hop index within this ask. `iter=0` is always the
+    /// initial decompose call; subsequent iters are decide calls;
+    /// the final iter is the synthesize call.
+    pub iter: u32,
+    pub kind: HopKind,
+    /// Sub-queries associated with this hop. The meaning depends on
+    /// `kind`:
+    ///
+    /// - [`HopKind::Decompose`]: the initial sub-queries the LLM
+    ///   broke the original user query into. These drive the
+    ///   `iter=1` retrieval round.
+    /// - [`HopKind::Decide`]: the *new* sub-queries the LLM
+    ///   emitted to drive the next retrieval round. Empty when the
+    ///   LLM signalled stop OR when `forced_stop = true` (cap hit
+    ///   or parse-degraded).
+    /// - [`HopKind::Synthesize`]: always empty — the final hop
+    ///   produces the user-visible answer, not more sub-queries.
+    #[serde(default)]
+    pub sub_queries: Vec<String>,
+    /// Number of *new* chunks the retrieval round contributed to the
+    /// pool (dedup'd by `chunk_id` — repeated hits from a previous
+    /// iter do not count). `0` for the decompose hop (no retrieval
+    /// yet) and the synthesize hop.
+    pub context_chunks_added: u32,
+    /// `true` when the pipeline cut the iter loop short because a
+    /// safety cap fired (`max_depth` / `max_total_sub_queries` /
+    /// `max_pool_chunks`) rather than because the LLM signalled
+    /// stop. The user-visible answer still reflects all chunks
+    /// accumulated up to that point — `forced_stop` is a tracing
+    /// signal, not a refusal.
+    pub forced_stop: bool,
+    /// Wall-clock latency of the LLM call for this hop, in
+    /// milliseconds. Useful for cost / latency analysis when a
+    /// `kebab eval` run records `Answer.hops`.
+    ///
+    /// `0` is overloaded: it means "no LLM call happened at this
+    /// hop" when (a) the hop was a Decide skipped due to
+    /// `forced_stop` (depth-cap or pool-cap fired before the LLM
+    /// was asked) or (b) the pool was empty before any decide
+    /// could run. Treat `0` as "absent or instantaneous" rather
+    /// than as a genuine measurement.
+    pub llm_call_ms: u32,
+}
+
+/// p9-fb-41: which stage of the multi-hop pipeline a [`HopRecord`]
+/// describes. The serde tag matches the wire shape so agents /
+/// CLIs can branch on the snake_case string without referencing
+/// the Rust enum.
+#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum HopKind {
+    /// First hop — LLM decomposed the user query into sub-queries.
+    Decompose,
+    /// Subsequent hop — LLM was asked whether more retrieval is
+    /// needed and either emitted new sub-queries (`continue`) or
+    /// returned an empty array (`stop`).
+    Decide,
+    /// Terminal hop — LLM produced the final user-visible answer
+    /// over the accumulated chunk pool.
+    Synthesize,
+}
+
 #[derive(Clone, Copy, Debug, Eq, Hash, PartialEq, Serialize, Deserialize)]
 #[serde(rename_all = "snake_case")]
 pub enum RefusalReason {
@@ -66,6 +170,24 @@ pub enum RefusalReason {
     /// 가 채워져 있을 수 있음 (사용자가 본 부분까지). RAG retrieval
     /// 자체는 정상 — 모델 generation 단계에서만 중단.
     LlmStreamAborted,
+    /// p9-fb-41: multi-hop pipeline 의 decompose LLM call 이 JSON
+    /// parse 가능한 sub-question array 를 반환하지 못함 (parse
+    /// error, 빈 응답, 또는 잘못된 형식). retrieval / synthesize
+    /// 단계 진입 못 함. CLI / MCP / TUI 가 받는 wire error code
+    /// = `"multi_hop_decompose_failed"` (PR-4 의 error_wire 매핑).
+    MultiHopDecomposeFailed,
+    /// p9-fb-41 PR-9c-1: post-synthesize NLI verification gate fired —
+    /// `NliScores::faithfulness()` (entailment channel) fell below
+    /// `[rag].nli_threshold`. Wire string = `"nli_verification_failed"`
+    /// (single source of truth: also the matching `error.v1.code`).
+    /// Multi-hop only; behavior wiring lands in PR-9c-2.
+    NliVerificationFailed,
+    /// p9-fb-41 PR-9c-1: NLI verifier was configured (threshold > 0)
+    /// but the model / runtime is unavailable (download failure,
+    /// missing tokenizer, ONNX session init error). Treated as a soft
+    /// refusal — the user sees an unverified-answer outcome rather
+    /// than crashing the ask. Wire string = `"nli_model_unavailable"`.
+    NliModelUnavailable,
 }
 
 #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
@@ -103,6 +225,81 @@ mod tests {
     use crate::citation::Citation;
     use time::macros::datetime;
 
+    /// p9-fb-41 PR-9c-1: pin the wire-side spelling of the new
+    /// `RefusalReason` variants. The strings here must match
+    /// `answer.schema.json::refusal_reason.enum` AND
+    /// `error.schema.json::code.enum` byte-for-byte (single source of
+    /// truth per spec §2.4).
+    #[test]
+    fn refusal_reason_nli_variants_serialize_to_snake_case() {
+        assert_eq!(
+            serde_json::to_string(&RefusalReason::NliVerificationFailed).unwrap(),
+            "\"nli_verification_failed\""
+        );
+        assert_eq!(
+            serde_json::to_string(&RefusalReason::NliModelUnavailable).unwrap(),
+            "\"nli_model_unavailable\""
+        );
+    }
+
+    /// p9-fb-41 PR-9c-1: `Answer.verification` is `Option<...>` with
+    /// `skip_serializing_if = None`. A `verification: None` answer
+    /// must NOT emit a `"verification"` key on the wire — the field
+    /// is additive and pre-v0.18 readers see no new key.
+    #[test]
+    fn answer_omits_verification_field_when_none() {
+        let ans = Answer {
+            answer: "x".into(),
+            citations: vec![],
+            grounded: true,
+            refusal_reason: None,
+            model: ModelRef {
+                id: "m".into(),
+                provider: "p".into(),
+                dimensions: None,
+            },
+            embedding: None,
+            prompt_template_version: PromptTemplateVersion("rag-v2".into()),
+            retrieval: AnswerRetrievalSummary {
+                trace_id: TraceId("t".into()),
+                mode: crate::SearchMode::Lexical,
+                k: 1,
+                score_gate: 0.0,
+                top_score: 0.0,
+                chunks_returned: 0,
+                chunks_used: 0,
+            },
+            usage: TokenUsage {
+                prompt_tokens: 0,
+                completion_tokens: 0,
+                latency_ms: 0,
+            },
+            created_at: datetime!(2026-05-09 12:00:00 UTC),
+            conversation_id: None,
+            turn_index: None,
+            hops: None,
+            verification: None,
+        };
+        let v = serde_json::to_value(&ans).unwrap();
+        assert!(
+            v.get("verification").is_none(),
+            "verification: None must be omitted from wire output, got: {v}"
+        );
+    }
+
+    #[test]
+    fn verification_summary_serializes_all_three_required_fields() {
+        let vs = VerificationSummary {
+            nli_score: 0.87,
+            nli_threshold: 0.5,
+            nli_passed: true,
+        };
+        let v = serde_json::to_value(vs).unwrap();
+        assert!((v["nli_score"].as_f64().unwrap() - 0.87).abs() < 1e-5);
+        assert!((v["nli_threshold"].as_f64().unwrap() - 0.5).abs() < 1e-5);
+        assert_eq!(v["nli_passed"], true);
+    }
+
     #[test]
     fn answer_citation_serializes_indexed_at_and_stale() {
         let ac = AnswerCitation {

crates/kebab-core/src/citation.rs

@@ -226,28 +226,25 @@ fn parse_hms_ms(s: &str) -> Result<u64> {
     let m: u64 = parts[1]
         .parse()
         .map_err(|_| anyhow::anyhow!("bad minutes in {:?} (input {s:?})", parts[1]))?;
-    let (sec, ms) = match parts[2].split_once('.') {
-        Some((s_part, ms_part)) => {
-            let sec: u64 = s_part
-                .parse()
-                .map_err(|_| anyhow::anyhow!("bad seconds in {s_part:?} (input {s:?})"))?;
-            // Pad/truncate to exactly 3 digits.
-            let mut ms_str = ms_part.to_owned();
-            while ms_str.len() < 3 {
-                ms_str.push('0');
-            }
-            ms_str.truncate(3);
-            let ms: u64 = ms_str
-                .parse()
-                .map_err(|_| anyhow::anyhow!("bad milliseconds in {ms_part:?} (input {s:?})"))?;
-            (sec, ms)
-        }
-        None => {
-            let sec: u64 = parts[2]
-                .parse()
-                .map_err(|_| anyhow::anyhow!("bad seconds in {:?} (input {s:?})", parts[2]))?;
-            (sec, 0)
+    let (sec, ms) = if let Some((s_part, ms_part)) = parts[2].split_once('.') {
+        let sec: u64 = s_part
+            .parse()
+            .map_err(|_| anyhow::anyhow!("bad seconds in {s_part:?} (input {s:?})"))?;
+        // Pad/truncate to exactly 3 digits.
+        let mut ms_str = ms_part.to_owned();
+        while ms_str.len() < 3 {
+            ms_str.push('0');
         }
+        ms_str.truncate(3);
+        let ms: u64 = ms_str
+            .parse()
+            .map_err(|_| anyhow::anyhow!("bad milliseconds in {ms_part:?} (input {s:?})"))?;
+        (sec, ms)
+    } else {
+        let sec: u64 = parts[2]
+            .parse()
+            .map_err(|_| anyhow::anyhow!("bad seconds in {:?} (input {s:?})", parts[2]))?;
+        (sec, 0)
     };
     Ok(h * 3_600_000 + m * 60_000 + sec * 1000 + ms)
 }

crates/kebab-core/src/lib.rs

@@ -56,8 +56,8 @@ pub use search::{
     TraceCandidate, TraceFusionInput, TraceTiming,
 };
 pub use answer::{
-    Answer, AnswerCitation, AnswerRetrievalSummary, ModelRef, RefusalReason, TokenUsage,
-    TraceId, Turn,
+    Answer, AnswerCitation, AnswerRetrievalSummary, HopKind, HopRecord, ModelRef,
+    RefusalReason, TokenUsage, TraceId, Turn, VerificationSummary,
 };
 pub use ingest::{IngestItem, IngestItemKind, IngestReport, SkipExamples};
 pub use jobs::{JobFilter, JobId, JobKind, JobRow, JobStatus};

crates/kebab-core/src/search.rs

@@ -471,7 +471,7 @@ mod tests {
             doc_path: WorkspacePath("a.md".into()),
             heading_path: vec![],
             section_label: None,
-            snippet: "".into(),
+            snippet: String::new(),
             citation: Citation::Line {
                 path: WorkspacePath("a.md".into()),
                 start: 1,
@@ -502,7 +502,7 @@ mod tests {
             doc_path: WorkspacePath("a.rs".into()),
             heading_path: vec![],
             section_label: None,
-            snippet: "".into(),
+            snippet: String::new(),
             citation: Citation::Code {
                 path: WorkspacePath("a.rs".into()),
                 line_start: 1,

crates/kebab-embed-local/Cargo.toml

@@ -20,3 +20,6 @@ anyhow    = { workspace = true }
 [dev-dependencies]
 tempfile = { workspace = true }
 serde_json = { workspace = true }
+
+[lints]
+workspace = true

crates/kebab-embed-local/src/lib.rs

@@ -158,7 +158,7 @@ impl Embedder for FastembedEmbedder {
             let guard = self
                 .inner
                 .lock()
-                .unwrap_or_else(|p| p.into_inner());
+                .unwrap_or_else(std::sync::PoisonError::into_inner);
             let batch: Vec<Vec<f32>> = guard
                 .embed(chunk_vec, Some(self.batch_size))
                 .context("fastembed: embed")?;

crates/kebab-embed/Cargo.toml

@@ -28,3 +28,6 @@ mock    = []
 
 [dev-dependencies]
 proptest = { workspace = true }
+
+[lints]
+workspace = true

crates/kebab-embed/src/lib.rs

@@ -59,7 +59,7 @@ pub fn assert_vector_shape(vecs: &[Vec<f32>], expected_dims: usize) {
 /// Panics on mismatch (test-only helper — callers are tests).
 pub fn assert_unit_norm(vecs: &[Vec<f32>], tolerance: f32) {
     for (i, v) in vecs.iter().enumerate() {
-        let norm_sq: f64 = v.iter().map(|&x| (x as f64) * (x as f64)).sum();
+        let norm_sq: f64 = v.iter().map(|&x| f64::from(x) * f64::from(x)).sum();
         let norm = norm_sq.sqrt() as f32;
         assert!(
             (norm - 1.0).abs() <= tolerance,

crates/kebab-embed/src/mock.rs

@@ -132,10 +132,10 @@ impl Embedder for MockEmbedder {
                 .collect();
 
             // L2-normalize. Skip the rare all-zero case to avoid 0/0 = NaN.
-            let norm_sq: f64 = v.iter().map(|&x| (x as f64) * (x as f64)).sum();
+            let norm_sq: f64 = v.iter().map(|&x| f64::from(x) * f64::from(x)).sum();
             if norm_sq > 0.0 {
                 let inv = (1.0 / norm_sq.sqrt()) as f32;
-                for x in v.iter_mut() {
+                for x in &mut v {
                     *x *= inv;
                 }
             }

crates/kebab-eval/Cargo.toml

@@ -28,3 +28,6 @@ uuid            = { workspace = true }
 [dev-dependencies]
 tempfile        = { workspace = true }
 rusqlite        = { workspace = true }
+
+[lints]
+workspace = true

crates/kebab-eval/src/compare.rs

@@ -260,8 +260,8 @@ pub fn render_report_md(report: &CompareReport) -> String {
             "| {} | {} | {} | {} | {} |",
             c.query_id,
             comparison_kind_label(c.kind),
-            c.a_hit_rank.map(|r| r.to_string()).unwrap_or_else(|| "—".into()),
-            c.b_hit_rank.map(|r| r.to_string()).unwrap_or_else(|| "—".into()),
+            c.a_hit_rank.map_or_else(|| "—".into(), |r| r.to_string()),
+            c.b_hit_rank.map_or_else(|| "—".into(), |r| r.to_string()),
             c.note.as_deref().unwrap_or(""),
         );
     }
@@ -308,7 +308,7 @@ fn extract_chunker_version(snapshot_json: &str) -> Option<String> {
     let v: serde_json::Value = serde_json::from_str(snapshot_json).ok()?;
     v.get("chunker_version")
         .and_then(|x| x.as_str())
-        .map(|s| s.to_owned())
+        .map(std::borrow::ToOwned::to_owned)
 }
 
 fn parse_results(
@@ -402,8 +402,7 @@ fn classify(
             // so refusal-flow queries (no expected_*) don't appear as
             // regressions.
             let has_expected = gq
-                .map(|g| !g.expected_chunk_ids.is_empty() || !g.expected_doc_ids.is_empty())
-                .unwrap_or(false);
+                .is_some_and(|g| !g.expected_chunk_ids.is_empty() || !g.expected_doc_ids.is_empty());
             if has_expected {
                 (ComparisonKind::Regression, Some("hit→miss".into()))
             } else {
@@ -426,7 +425,7 @@ fn build_deltas(
         if a.is_nan() || b.is_nan() {
             serde_json::Value::Null
         } else {
-            serde_json::Value::from((b - a) as f64)
+            serde_json::Value::from(f64::from(b - a))
         }
     }
     let mut hit = serde_json::Map::new();

crates/kebab-eval/src/metrics.rs

@@ -270,7 +270,21 @@ pub(crate) fn aggregate_from_rows(
         // recall@k_doc (doc-level, requires non-empty expected_doc_ids
         // and `>0` is the "should retrieve" condition; refusal queries
         // (`expected_doc_ids = []`) are excluded by spec).
-        if !gq.expected_doc_ids.is_empty() {
+        if gq.expected_doc_ids.is_empty() {
+            // refusal_correctness: golden marks "should refuse" via empty
+            // expected_doc_ids. We can only judge this on RAG runs — a
+            // lexical-only run produces no Answer, so "refusal" is
+            // undefined. Excluding such queries from the denominator
+            // (rather than counting them as failures) keeps the metric
+            // honest: a search-only run reports refusal_correctness as
+            // NaN/null, not 0.0.
+            if let Some(ans) = &qr.answer {
+                refusal_denom += 1;
+                if !ans.grounded {
+                    refusal_num += 1;
+                }
+            }
+        } else {
             let expected_docs: HashSet<&DocumentId> = gq.expected_doc_ids.iter().collect();
             for k in TOP_K_VARIANTS {
                 let entry = recall_at_k_doc.get_mut(k).expect("init");
@@ -285,20 +299,6 @@ pub(crate) fn aggregate_from_rows(
                 let frac = covered as f64 / expected_docs.len() as f64;
                 entry.0 += frac;
             }
-        } else {
-            // refusal_correctness: golden marks "should refuse" via empty
-            // expected_doc_ids. We can only judge this on RAG runs — a
-            // lexical-only run produces no Answer, so "refusal" is
-            // undefined. Excluding such queries from the denominator
-            // (rather than counting them as failures) keeps the metric
-            // honest: a search-only run reports refusal_correctness as
-            // NaN/null, not 0.0.
-            if let Some(ans) = &qr.answer {
-                refusal_denom += 1;
-                if !ans.grounded {
-                    refusal_num += 1;
-                }
-            }
         }
 
         // groundedness + citation_coverage (only meaningful with RAG
@@ -532,6 +532,8 @@ mod tests {
             created_at: OffsetDateTime::UNIX_EPOCH,
             conversation_id: None,
             turn_index: None,
+            hops: None,
+            verification: None,
         }
     }
 

crates/kebab-eval/src/runner.rs

@@ -179,6 +179,10 @@ fn execute_query(app: &App, gq: &GoldenQuery, opts: &EvalRunOpts) -> QueryResult
             history: Vec::new(),
             conversation_id: None,
             turn_index: None,
+            // p9-fb-41: golden eval baseline runs are single-pass; the
+            // multi-hop path is opted into per query via a future
+            // fixture flag (PR-4+) once the runner learns to dispatch.
+            multi_hop: false,
         };
         match app.ask(&gq.query, ask_opts) {
             Ok(ans) => Some(ans),

crates/kebab-eval/tests/fixtures/eval/run-1.json

@@ -5,7 +5,7 @@
       "chunk_id": "chunk000000000000000000000000000000",
       "doc_id": "doc00000000000000000000000000000000",
       "heading_path": [],
-      "score": 0.3429983854293823
+      "score": 0.35202541947364807
     },
     "has_answer": false,
     "hits_count": 1,
@@ -19,7 +19,7 @@
       "chunk_id": "chunk000000000000000000000000000002",
       "doc_id": "doc00000000000000000000000000000002",
       "heading_path": [],
-      "score": 0.3585492968559265
+      "score": 0.3414848744869232
     },
     "has_answer": false,
     "hits_count": 1,

crates/kebab-eval/tests/loader.rs

@@ -38,7 +38,44 @@ fn loads_minimal_well_formed_yaml() {
     assert_eq!(qs[1].difficulty.as_deref(), Some("easy"));
 }
 
-// ── 2. duplicate IDs error lists every offender (sorted, deduplicated) ───────
+// ── 2. fb-41 multi-hop golden fixture loads + sanity-checks ─────────────────
+
+/// fb-41 baseline + post-merge Δ measurement fixture. The shared
+/// loader must accept `fixtures/multi_hop_golden.yaml` and the bucket
+/// distribution must stay 5 cross-doc + 5 intra-doc + 5 single-fact
+/// negative — curators dropping or re-id'ing a question hit a clear
+/// failure mode here before it reaches the runner.
+#[test]
+fn loads_multi_hop_golden_fixture() {
+    let path = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
+        .join("..")
+        .join("..")
+        .join("fixtures")
+        .join("multi_hop_golden.yaml");
+    let qs = load_golden_set(&path).expect("multi_hop_golden.yaml must parse");
+
+    assert_eq!(qs.len(), 15, "fb-41 fixture must have 15 questions");
+
+    let cross_doc = qs.iter().filter(|q| q.id.starts_with("mh-c-")).count();
+    let intra_doc = qs.iter().filter(|q| q.id.starts_with("mh-i-")).count();
+    let single = qs.iter().filter(|q| q.id.starts_with("mh-s-")).count();
+    assert_eq!(cross_doc, 5, "expected 5 mh-c-* (cross-doc) questions");
+    assert_eq!(intra_doc, 5, "expected 5 mh-i-* (intra-doc) questions");
+    assert_eq!(single, 5, "expected 5 mh-s-* (single-fact negative) questions");
+
+    // Every question carries at least one `must_contain` so the
+    // rule-based answer-correctness metric (P5-2) has a signal even
+    // before `expected_chunk_ids` are filled in.
+    for q in &qs {
+        assert!(
+            !q.must_contain.is_empty(),
+            "{}: must_contain is empty — baseline measurement needs a signal",
+            q.id
+        );
+    }
+}
+
+// ── 3. duplicate IDs error lists every offender (sorted, deduplicated) ───────
 
 #[test]
 fn rejects_duplicate_ids() {

crates/kebab-eval/tests/metrics_and_compare.rs

@@ -143,7 +143,7 @@ fn env_guard() -> std::sync::MutexGuard<'static, ()> {
     static M: OnceLock<Mutex<()>> = OnceLock::new();
     M.get_or_init(|| Mutex::new(()))
         .lock()
-        .unwrap_or_else(|e| e.into_inner())
+        .unwrap_or_else(std::sync::PoisonError::into_inner)
 }
 
 #[test]

crates/kebab-eval/tests/runner.rs

@@ -147,7 +147,7 @@ fn lexical_opts() -> EvalRunOpts {
 /// guard must outlive the call so concurrent tests don't reset the
 /// var mid-run.
 fn run_with_golden<F: FnOnce() -> R, R>(yaml: &Path, f: F) -> R {
-    let _g = GOLDEN_ENV_LOCK.lock().unwrap_or_else(|p| p.into_inner());
+    let _g = GOLDEN_ENV_LOCK.lock().unwrap_or_else(std::sync::PoisonError::into_inner);
     // SAFETY: `KEBAB_EVAL_GOLDEN` is a benign env var; the GOLDEN_ENV_LOCK
     // serializes mutations so concurrent tests don't race.
     unsafe {

crates/kebab-llm-local/Cargo.toml

@@ -34,3 +34,6 @@ anyhow     = { workspace = true }
 # `tokio::*` symbols, so the public/runtime API stays sync.
 wiremock   = { workspace = true }
 tokio      = { workspace = true, features = ["macros", "rt"] }
+
+[lints]
+workspace = true

crates/kebab-llm-local/src/ollama.rs

@@ -48,10 +48,17 @@ use serde::{Deserialize, Serialize};
 
 use crate::error::LlmError;
 
-/// Hard ceiling on a single HTTP exchange. Cold-loading a 14B model on
-/// first call can take ~30s; 5 minutes is generous without being
-/// open-ended.
-const REQUEST_TIMEOUT: Duration = Duration::from_secs(300);
+// v0.17.0 post-dogfood: the per-request ceiling now lives in
+// `kebab_config::LlmCfg::request_timeout_secs` (default 300s) so users
+// running larger models on CPU-only hosts can extend it without a
+// rebuild. Cold-loading an 8B+ model on first call routinely takes
+// 60-90 s plus multi-minute inference; 300s was the legacy hard
+// ceiling and remains the default for back-compat.
+//
+// Edge case: `request_timeout_secs = 0` becomes
+// `Duration::from_secs(0)` which is reqwest's "fail immediately", NOT
+// "disable". The field doc explains the workaround (use u64::MAX or a
+// large finite value).
 
 /// `reqwest::blocking` adapter implementing [`LanguageModel`] over Ollama's
 /// local HTTP API. Construction is cheap and offline; the first network
@@ -79,7 +86,7 @@ impl OllamaLanguageModel {
     pub fn new(config: &kebab_config::Config) -> anyhow::Result<Self> {
         let llm = &config.models.llm;
         let client = reqwest::blocking::Client::builder()
-            .timeout(REQUEST_TIMEOUT)
+            .timeout(Duration::from_secs(llm.request_timeout_secs))
             .build()?;
         Ok(Self {
             client,
@@ -262,9 +269,11 @@ struct OllamaLine {
 ///
 /// Timeout invariant: the iterator has no inherent stop condition for an
 /// indefinitely-stalled server — only the underlying
-/// `reqwest::blocking::Client`'s read timeout (`REQUEST_TIMEOUT`, 300s)
-/// breaks the hang. Callers needing tighter cancellation should adjust
-/// the client timeout in [`OllamaLanguageModel::new`].
+/// `reqwest::blocking::Client`'s read timeout (configured via
+/// `kebab_config::LlmCfg::request_timeout_secs`, default 300 s) breaks
+/// the hang. Callers needing tighter / looser bounds should set
+/// `[models.llm] request_timeout_secs = N` (or
+/// `KEBAB_MODELS_LLM_REQUEST_TIMEOUT_SECS=N`) before building.
 struct OllamaStream {
     reader: BufReader<reqwest::blocking::Response>,
     line_buf: Vec<u8>,
@@ -391,9 +400,9 @@ impl Iterator for OllamaStream {
                     // u32 saturation: even ~4G tokens is implausible for a
                     // single chat turn; we still saturate rather than
                     // panic on the unlikely case.
-                    prompt_tokens: prompt_tokens.min(u32::MAX as u64) as u32,
-                    completion_tokens: completion_tokens.min(u32::MAX as u64) as u32,
-                    latency_ms: (total_duration_ns / 1_000_000).min(u32::MAX as u64) as u32,
+                    prompt_tokens: prompt_tokens.min(u64::from(u32::MAX)) as u32,
+                    completion_tokens: completion_tokens.min(u64::from(u32::MAX)) as u32,
+                    latency_ms: (total_duration_ns / 1_000_000).min(u64::from(u32::MAX)) as u32,
                 };
                 return Some(Ok(TokenChunk::Done {
                     finish_reason,

crates/kebab-llm/Cargo.toml

@@ -19,3 +19,6 @@ mock    = []
 
 [dev-dependencies]
 proptest = { workspace = true }
+
+[lints]
+workspace = true

crates/kebab-mcp/Cargo.toml

@@ -27,3 +27,6 @@ kebab-core   = { path = "../kebab-core" }
 
 [dev-dependencies]
 tempfile = { workspace = true }
+
+[lints]
+workspace = true

crates/kebab-mcp/src/lib.rs

@@ -49,7 +49,7 @@ pub fn build_tools_vec() -> Vec<Tool> {
         ),
         Tool::new(
             "ask",
-            "RAG question answering over the knowledge base. Returns answer.v1 JSON. Pass session_id for multi-turn context.",
+            "RAG question answering over the knowledge base. Returns answer.v1 JSON. Pass session_id for multi-turn context. Set multi_hop=true for compound / cross-doc questions (decompose → retrieve → synthesize; 2-5× LLM cost; per-hop trace on Answer.hops).",
             schema_for_type::<tools::ask::AskInput>(),
         ),
         Tool::new(

crates/kebab-mcp/src/tools/ask.rs

@@ -20,6 +20,15 @@ pub struct AskInput {
     pub session_id: Option<String>,
     /// Optional retrieval mode override ("lexical" / "vector" / "hybrid"). Default "hybrid".
     pub mode: Option<String>,
+    /// p9-fb-41: opt the ask into the multi-hop pipeline. Default `false`.
+    /// When `true`, the query is decomposed into sub-questions, each
+    /// retrieved independently, then synthesized over the merged
+    /// chunk pool. Cost trade-off: 2–5× LLM calls vs. single-pass.
+    /// Use for compound questions / cross-doc reasoning / prereq
+    /// chains; keep `false` for simple fact lookups. The full
+    /// per-hop trace (`decompose` / `decide` / `synthesize`) is
+    /// exposed on `Answer.hops`.
+    pub multi_hop: Option<bool>,
 }
 
 pub fn handle(state: &KebabAppState, input: AskInput) -> CallToolResult {
@@ -38,6 +47,7 @@ pub fn handle(state: &KebabAppState, input: AskInput) -> CallToolResult {
         history: Vec::new(),
         conversation_id: None,
         turn_index: None,
+        multi_hop: input.multi_hop.unwrap_or(false),
     };
     let cfg_clone = (*state.config).clone();
     let result = match input.session_id {

crates/kebab-mcp/tests/tools_call_ask.rs

@@ -55,6 +55,7 @@ async fn ask_tool_returns_answer_v1_with_refusal_on_empty_kb() {
                 // Test env uses provider="none" — Hybrid would hard-error on embedding.
                 // Pass Lexical explicitly so the test stays functional.
                 mode: Some("lexical".to_string()),
+                multi_hop: None,
             },
         )
     })
@@ -64,8 +65,7 @@ async fn ask_tool_returns_answer_v1_with_refusal_on_empty_kb() {
     // Empty KB → refusal (grounded:false) is normal — NOT isError.
     assert!(
         !result.is_error.unwrap_or(false),
-        "expected isError=false on refusal, got {:?}",
-        result
+        "expected isError=false on refusal, got {result:?}"
     );
 
     let content = result
@@ -85,7 +85,7 @@ async fn ask_tool_returns_answer_v1_with_refusal_on_empty_kb() {
         "response should carry schema_version=answer.v1"
     );
     assert_eq!(
-        v.get("grounded").and_then(|b| b.as_bool()),
+        v.get("grounded").and_then(serde_json::Value::as_bool),
         Some(false),
         "empty KB should produce grounded=false"
     );

crates/kebab-mcp/tests/tools_call_ask_multi_hop.rs

@@ -0,0 +1,148 @@
+//! p9-fb-41 PR-5: MCP `ask` tool with `multi_hop: true` argument.
+//!
+//! Two Ollama-free pins:
+//!
+//! 1. `ask_tool_routes_multi_hop_true_to_decompose_first` — multi-hop
+//!    dispatch differs from single-pass on dispatch shape. Single-pass
+//!    retrieves *first* (empty KB → `NoChunks` refusal, no LLM call,
+//!    `grounded=false`). Multi-hop calls *decompose first* (no
+//!    retrieval yet), so an empty KB + no Ollama yields `error.v1`
+//!    with `code=model_unreachable` — different wire shape than the
+//!    refusal envelope. The two surfaces' divergence is the signal
+//!    that the `multi_hop` arg actually routed the dispatch.
+//! 2. `ask_input_schema_advertises_multi_hop_field` — `AskInput`'s
+//!    `JsonSchema` exposes the new field so MCP host capability
+//!    discovery (tools/list) renders it for agents.
+//!
+//! A live-Ollama end-to-end multi-hop pin lands in a follow-up
+//! `#[ignore]` test (same pattern as `wire_ask_stale.rs`).
+
+use kebab_config::Config;
+use kebab_core::SourceScope;
+use kebab_mcp::{KebabAppState, KebabHandler};
+use rmcp::model::RawContent;
+
+fn minimal_config(data_dir: &std::path::Path, workspace_root: &std::path::Path) -> Config {
+    let mut cfg = Config::defaults();
+    cfg.storage.data_dir = data_dir.to_string_lossy().into_owned();
+    cfg.storage.model_dir = data_dir.join("models").to_string_lossy().into_owned();
+    cfg.workspace.root = workspace_root.to_string_lossy().into_owned();
+    cfg.workspace.exclude.clear();
+    cfg.models.embedding.provider = "none".to_string();
+    cfg.models.embedding.dimensions = 0;
+    // Force the LLM endpoint to a known-unreachable port so this test
+    // is robust against whether a real Ollama happens to be running
+    // on 127.0.0.1:11434 (the developer's box; CI; etc.). The
+    // `request_timeout_secs = 5` gives slow CI / Docker network stacks
+    // enough headroom that *some* error fires deterministically — the
+    // dispatch contract below only cares that `is_error` flipped, not
+    // which specific error code surfaced.
+    cfg.models.llm.endpoint = "http://127.0.0.1:1".to_string();
+    cfg.models.llm.request_timeout_secs = 5;
+    cfg
+}
+
+/// The dispatch contract: with an empty KB, single-pass `ask` short-
+/// circuits at retrieval (no LLM call) and returns a refusal Answer
+/// (`grounded=false`, `isError=false`). Multi-hop calls *decompose
+/// first*, so the same empty KB + unreachable LLM yields `error.v1`
+/// with `code=model_unreachable` (`isError=true`). The divergence
+/// confirms the `multi_hop` arg actually rerouted the dispatch.
+#[tokio::test]
+async fn ask_tool_routes_multi_hop_true_to_decompose_first() {
+    let dir = tempfile::tempdir().unwrap();
+    let data_dir = dir.path().join("data");
+    let workspace_root = dir.path().join("notes");
+    std::fs::create_dir_all(&data_dir).unwrap();
+    std::fs::create_dir_all(&workspace_root).unwrap();
+    let cfg = minimal_config(&data_dir, &workspace_root);
+
+    let scope = SourceScope {
+        root: workspace_root.clone(),
+        include: vec![],
+        exclude: vec![],
+    };
+    let _ = kebab_app::ingest_with_config(cfg.clone(), scope, false).unwrap();
+
+    let state = KebabAppState::new(cfg, None);
+    let handler = KebabHandler::new(state);
+
+    // Multi-hop branch — decompose runs first, hits the unreachable
+    // endpoint, MCP wraps as error.v1.
+    let state_mh = handler.state().clone();
+    let mh = tokio::task::spawn_blocking(move || {
+        kebab_mcp::tools::ask::handle(
+            &state_mh,
+            kebab_mcp::tools::ask::AskInput {
+                query: "compound about X and Y".to_string(),
+                session_id: None,
+                mode: Some("lexical".to_string()),
+                multi_hop: Some(true),
+            },
+        )
+    })
+    .await
+    .unwrap();
+    assert!(
+        mh.is_error.unwrap_or(false),
+        "multi_hop=true must reach the LLM (decompose first) — got {mh:?}"
+    );
+    let mh_text = match &mh.content.first().unwrap().raw {
+        RawContent::Text(t) => t.text.clone(),
+        other => panic!("expected text, got {other:?}"),
+    };
+    let mh_v: serde_json::Value = serde_json::from_str(&mh_text).unwrap();
+    assert_eq!(mh_v["schema_version"], "error.v1");
+    // The dispatch contract is "multi-hop reached the LLM" — i.e.
+    // `is_error` fires because decompose tried to talk to the LLM and
+    // failed. Which *specific* error code lands (`model_unreachable`
+    // on fast ECONNREFUSED hosts, `timeout` on slow connect-timeout
+    // stacks, etc.) is implementation detail of the host TCP/HTTP
+    // path; pinning it here would just produce flakes on slow CI.
+
+    // Single-pass branch — empty KB short-circuits at retrieve, no LLM
+    // call happens, refusal Answer comes back as isError=false.
+    let state_sp = handler.state().clone();
+    let sp = tokio::task::spawn_blocking(move || {
+        kebab_mcp::tools::ask::handle(
+            &state_sp,
+            kebab_mcp::tools::ask::AskInput {
+                query: "anything".to_string(),
+                session_id: None,
+                mode: Some("lexical".to_string()),
+                multi_hop: Some(false),
+            },
+        )
+    })
+    .await
+    .unwrap();
+    assert!(
+        !sp.is_error.unwrap_or(false),
+        "single-pass empty-KB refusal must NOT be isError — got {sp:?}"
+    );
+    let sp_text = match &sp.content.first().unwrap().raw {
+        RawContent::Text(t) => t.text.clone(),
+        other => panic!("expected text, got {other:?}"),
+    };
+    let sp_v: serde_json::Value = serde_json::from_str(&sp_text).unwrap();
+    assert_eq!(sp_v["schema_version"], "answer.v1");
+    assert_eq!(sp_v["grounded"], false);
+}
+
+/// AskInput's JSON-schema (rendered for tools/list) advertises the
+/// new `multi_hop` field. Pins agent / MCP host capability discovery
+/// against accidental schema-rename or omission.
+#[test]
+fn ask_input_schema_advertises_multi_hop_field() {
+    let schema = schemars::schema_for!(kebab_mcp::tools::ask::AskInput);
+    let v = serde_json::to_value(&schema).unwrap();
+    let props = v
+        .get("properties")
+        .and_then(|p| p.as_object())
+        .expect("AskInput schema must declare properties");
+    assert!(
+        props.contains_key("multi_hop"),
+        "AskInput.multi_hop must surface in the JsonSchema — got keys: {:?}",
+        props.keys().collect::<Vec<_>>()
+    );
+}

crates/kebab-mcp/tests/tools_call_doctor.rs

@@ -44,7 +44,7 @@ async fn doctor_tool_returns_doctor_v1_json() {
     // `ok` boolean must be present (value may be false in CI where Ollama
     // is not reachable — that's expected and acceptable).
     assert!(
-        v.get("ok").and_then(|b| b.as_bool()).is_some(),
+        v.get("ok").and_then(serde_json::Value::as_bool).is_some(),
         "`ok` field missing in doctor.v1 response: {v}"
     );
 }

crates/kebab-mcp/tests/tools_call_fetch.rs

@@ -98,8 +98,7 @@ async fn fetch_tool_chunk_returns_fetch_result_v1() {
 
     assert!(
         !result.is_error.unwrap_or(false),
-        "expected isError=false, got {:?}",
-        result
+        "expected isError=false, got {result:?}"
     );
 
     let content = result
@@ -123,7 +122,7 @@ async fn fetch_tool_chunk_returns_fetch_result_v1() {
         "kind must be 'chunk'"
     );
     assert!(
-        v.get("chunk").is_some_and(|c| c.is_object()),
+        v.get("chunk").is_some_and(serde_json::Value::is_object),
         "chunk payload must be populated for kind=chunk"
     );
 }

crates/kebab-mcp/tests/tools_call_ingest_file.rs

@@ -49,7 +49,7 @@ async fn ingest_file_tool_returns_ingest_report_v1() {
         v.get("schema_version").and_then(|s| s.as_str()),
         Some("ingest_report.v1")
     );
-    assert_eq!(v.get("new").and_then(|n| n.as_u64()), Some(1));
+    assert_eq!(v.get("new").and_then(serde_json::Value::as_u64), Some(1));
 }
 
 #[tokio::test]
@@ -91,7 +91,7 @@ async fn ingest_file_tool_idempotent_on_second_call() {
         other => panic!("expected text, got {other:?}"),
     };
     let v1: serde_json::Value = serde_json::from_str(text1).unwrap();
-    assert_eq!(v1.get("new").and_then(|n| n.as_u64()), Some(1));
+    assert_eq!(v1.get("new").and_then(serde_json::Value::as_u64), Some(1));
 
     // Second call — same content, expect unchanged=1.
     let r2 = tokio::task::spawn_blocking({
@@ -112,6 +112,6 @@ async fn ingest_file_tool_idempotent_on_second_call() {
         other => panic!("expected text, got {other:?}"),
     };
     let v2: serde_json::Value = serde_json::from_str(text2).unwrap();
-    assert_eq!(v2.get("new").and_then(|n| n.as_u64()), Some(0), "{v2:?}");
-    assert_eq!(v2.get("unchanged").and_then(|n| n.as_u64()), Some(1), "{v2:?}");
+    assert_eq!(v2.get("new").and_then(serde_json::Value::as_u64), Some(0), "{v2:?}");
+    assert_eq!(v2.get("unchanged").and_then(serde_json::Value::as_u64), Some(1), "{v2:?}");
 }

crates/kebab-mcp/tests/tools_call_ingest_stdin.rs

@@ -52,7 +52,7 @@ async fn ingest_stdin_tool_returns_ingest_report_v1() {
         v.get("schema_version").and_then(|s| s.as_str()),
         Some("ingest_report.v1")
     );
-    assert_eq!(v.get("new").and_then(|n| n.as_u64()), Some(1));
+    assert_eq!(v.get("new").and_then(serde_json::Value::as_u64), Some(1));
 }
 
 #[tokio::test]

crates/kebab-mcp/tests/tools_call_schema.rs

@@ -49,8 +49,7 @@ async fn schema_tool_returns_schema_v1_json() {
 
     assert!(
         !result.is_error.unwrap_or(false),
-        "expected isError=false on healthy schema, got {:?}",
-        result
+        "expected isError=false on healthy schema, got {result:?}"
     );
 
     let content = result.content.first().expect("expected at least one content item");
@@ -68,7 +67,7 @@ async fn schema_tool_returns_schema_v1_json() {
         "unexpected schema_version in: {v}"
     );
     assert_eq!(
-        v.get("capabilities").and_then(|c| c.get("mcp_server")).and_then(|b| b.as_bool()),
+        v.get("capabilities").and_then(|c| c.get("mcp_server")).and_then(serde_json::Value::as_bool),
         Some(true),
         "mcp_server capability flag should be true after fb-30",
     );

crates/kebab-mcp/tests/tools_call_search.rs

@@ -71,8 +71,7 @@ async fn search_tool_returns_search_response_v1() {
 
     assert!(
         !result.is_error.unwrap_or(false),
-        "expected isError=false, got {:?}",
-        result
+        "expected isError=false, got {result:?}"
     );
 
     let content = result
@@ -108,7 +107,7 @@ async fn search_tool_returns_search_response_v1() {
     );
     // truncated must be present (bool); next_cursor may be null on last page.
     assert!(
-        v.get("truncated").and_then(|t| t.as_bool()).is_some(),
+        v.get("truncated").and_then(serde_json::Value::as_bool).is_some(),
         "envelope should carry truncated:bool"
     );
     assert!(
@@ -172,8 +171,7 @@ async fn search_with_doc_id_filter_returns_only_target() {
     );
     assert!(
         !unfiltered.is_error.unwrap_or(false),
-        "unfiltered search failed: {:?}",
-        unfiltered
+        "unfiltered search failed: {unfiltered:?}"
     );
     let unfiltered_text = match &unfiltered.content.first().unwrap().raw {
         RawContent::Text(t) => t.text.clone(),
@@ -211,8 +209,7 @@ async fn search_with_doc_id_filter_returns_only_target() {
     );
     assert!(
         !filtered.is_error.unwrap_or(false),
-        "filtered search failed: {:?}",
-        filtered
+        "filtered search failed: {filtered:?}"
     );
     let filtered_text = match &filtered.content.first().unwrap().raw {
         RawContent::Text(t) => t.text.clone(),

crates/kebab-nli/Cargo.toml

@@ -0,0 +1,33 @@
+[package]
+name = "kebab-nli"
+version       = { workspace = true }
+edition       = { workspace = true }
+rust-version  = { workspace = true }
+license       = { workspace = true }
+repository    = { workspace = true }
+description   = "fb-41: NLI-based post-synthesis verification (XNLI mDeBERTa-v3). PR-9a = trait + scaffolding; ONNX inference lands in PR-9b."
+
+[dependencies]
+# PR-9b: ONNX inference path activated. ort / tokenizers / hf-hub / ndarray
+# all source from `[workspace.dependencies]` so the workspace pins a single
+# version + feature set for the whole NLI + embed stack.
+kebab-config = { path = "../kebab-config" }
+anyhow       = { workspace = true }
+serde        = { workspace = true }
+# ort: extend the workspace pin with `download-binaries` so kebab-nli
+# can link the ONNX runtime when fastembed is NOT in the build graph
+# (e.g. `cargo test -p kebab-nli` alone, where the per-crate feature
+# union excludes kebab-embed-local + fastembed). In workspace-wide
+# builds the feature gets union'd with fastembed's identical opt-in
+# so no extra runtime gets pulled.
+ort          = { workspace = true, features = ["download-binaries"] }
+tokenizers   = { workspace = true }
+hf-hub       = { workspace = true }
+ndarray      = { workspace = true }
+tracing      = { workspace = true }
+
+[dev-dependencies]
+tempfile     = { workspace = true }
+
+[lints]
+workspace = true

crates/kebab-nli/src/lib.rs

@@ -0,0 +1,114 @@
+//! `kebab-nli` — NLI-based post-synthesis verification for multi-hop RAG.
+//!
+//! fb-41 introduces a mDeBERTa-v3 XNLI verifier that runs on
+//! `(packed_chunks, generated_answer)` after synthesize. If
+//! `NliScores::faithfulness()` < threshold the rag crate refuses the answer
+//! with `NliVerificationFailed`. PR-9a (this file) is the trait surface +
+//! scaffolding only — `OnnxNliVerifier::score` returns a stub error until
+//! PR-9b adds the real ONNX inference path.
+
+use serde::{Deserialize, Serialize};
+
+pub mod onnx;
+
+pub use onnx::OnnxNliVerifier;
+
+/// Three-channel XNLI output. Channel order matches the standard XNLI
+/// `id2label` mapping `[entailment, neutral, contradiction]` shipped with
+/// the Xenova mDeBERTa-v3 model.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Serialize, Deserialize)]
+pub struct NliScores {
+    pub entailment: f32,
+    pub neutral: f32,
+    pub contradiction: f32,
+}
+
+impl NliScores {
+    /// Faithfulness score = entailment channel. The rag crate compares this
+    /// against `rag.nli_threshold` to decide whether to refuse.
+    pub fn faithfulness(&self) -> f32 {
+        self.entailment
+    }
+
+    /// Wrap raw XNLI logits (`[entailment, neutral, contradiction]`) into
+    /// a normalised `NliScores`. Applies a numerically-stable softmax3.
+    pub fn from_xnli_logits(logits: [f32; 3]) -> Self {
+        let probs = softmax3(logits);
+        Self {
+            entailment: probs[0],
+            neutral: probs[1],
+            contradiction: probs[2],
+        }
+    }
+}
+
+/// Abstract NLI verifier. `score` is called with `(premise = packed chunks,
+/// hypothesis = generated answer)` — the standard NLI direction (premise
+/// entails hypothesis ⇒ answer is grounded in retrieved evidence).
+pub trait NliVerifier: Send + Sync {
+    fn score(&self, premise: &str, hypothesis: &str) -> anyhow::Result<NliScores>;
+}
+
+/// Numerically stable 3-way softmax (subtract max for log-sum-exp safety).
+/// Private — call sites should go through `NliScores::from_xnli_logits`.
+fn softmax3(logits: [f32; 3]) -> [f32; 3] {
+    let max = logits[0].max(logits[1]).max(logits[2]);
+    let e0 = (logits[0] - max).exp();
+    let e1 = (logits[1] - max).exp();
+    let e2 = (logits[2] - max).exp();
+    let sum = e0 + e1 + e2;
+    [e0 / sum, e1 / sum, e2 / sum]
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn approx_eq(a: f32, b: f32, eps: f32) -> bool {
+        (a - b).abs() <= eps
+    }
+
+    #[test]
+    fn softmax3_normalises_to_unit() {
+        let p = softmax3([1.0, 2.0, 3.0]);
+        assert!(p.iter().all(|x| *x > 0.0));
+        assert!(approx_eq(p[0] + p[1] + p[2], 1.0, 1e-6));
+        // Monotonic: larger logit ⇒ larger probability.
+        assert!(p[0] < p[1] && p[1] < p[2]);
+    }
+
+    #[test]
+    fn softmax3_is_invariant_to_constant_shift() {
+        let a = softmax3([1.0, 2.0, 3.0]);
+        let b = softmax3([101.0, 102.0, 103.0]);
+        for i in 0..3 {
+            assert!(
+                approx_eq(a[i], b[i], 1e-6),
+                "channel {i} drifted: a={a:?} b={b:?}"
+            );
+        }
+    }
+
+    #[test]
+    fn nli_scores_from_xnli_logits_orders_correctly() {
+        // entailment dominates ⇒ entailment is the max probability channel.
+        let s = NliScores::from_xnli_logits([5.0, 1.0, 0.5]);
+        assert!(s.entailment > s.neutral);
+        assert!(s.entailment > s.contradiction);
+        assert!(approx_eq(
+            s.entailment + s.neutral + s.contradiction,
+            1.0,
+            1e-6
+        ));
+    }
+
+    #[test]
+    fn faithfulness_returns_entailment_channel() {
+        let s = NliScores {
+            entailment: 0.7,
+            neutral: 0.2,
+            contradiction: 0.1,
+        };
+        assert!(approx_eq(s.faithfulness(), 0.7, f32::EPSILON));
+    }
+}

crates/kebab-nli/src/onnx.rs

@@ -0,0 +1,408 @@
+//! ONNX-backed `NliVerifier` adapter (mDeBERTa-v3 XNLI).
+//!
+//! `new` resolves the cache directory from
+//! `config.storage.model_dir/nli/<sanitized-model-id>/` (matching the
+//! fastembed adapter's pattern of `model_dir/fastembed/`) and stamps it
+//! on `self`. The (potentially network-bound) model + tokenizer download
+//! is deferred to the first `score` call via `OnceLock<Session>` /
+//! `OnceLock<Tokenizer>` — keeping `new` cheap so the rag crate can
+//! construct the verifier eagerly during `App` boot without paying for
+//! a model load on every CLI invocation.
+//!
+//! Per design §2.2.2 (Lazy init), §2.2.3 (truncation = `OnlyFirst`,
+//! premise truncates, hypothesis preserved). The model id flows from
+//! `config.models.nli.model`; `config.models.nli.provider` selects the
+//! verifier impl (only `"onnx"` is implemented in v0.18).
+
+use std::path::PathBuf;
+use std::sync::OnceLock;
+
+use anyhow::{Context, Result, anyhow};
+use kebab_config::expand_path;
+use ort::session::Session;
+use tokenizers::{
+    Tokenizer, TruncationDirection, TruncationParams, TruncationStrategy,
+};
+
+use crate::{NliScores, NliVerifier};
+
+/// Filename inside the HF repo (NOT a path on disk). The Xenova repo
+/// packages the mDeBERTa-v3-base XNLI multilingual checkpoint (the
+/// default `config.models.nli.model` — see `kebab-config::NliCfg::defaults`)
+/// as ONNX under this path; the tokenizer ships at `tokenizer.json`.
+const HF_MODEL_FILE: &str = "onnx/model.onnx";
+/// Filename inside the HF repo (NOT a path on disk).
+const HF_TOKENIZER_FILE: &str = "tokenizer.json";
+
+/// Subdirectory under `config.storage.model_dir` where the NLI adapter
+/// writes / reads ONNX + tokenizer files. Mirrors the fastembed
+/// adapter's `model_dir/fastembed/` layout.
+const NLI_CACHE_SUBDIR: &str = "nli";
+
+/// XNLI label order in the Xenova mDeBERTa-v3 checkpoint: the model's
+/// output logits are `[entailment, neutral, contradiction]`. Pinned as
+/// a constant so a future model swap (different label order) is a
+/// single-site change.
+const LOGITS_LEN: usize = 3;
+
+/// Max input length passed to the tokenizer. mDeBERTa-v3 is trained
+/// at 512-token context, matches the Xenova ONNX export's positional
+/// embedding shape. `OnlyFirst` strategy makes the premise (which is
+/// allowed to be the packed-chunks context) absorb the truncation;
+/// the hypothesis (the generated answer) is preserved.
+const MAX_TOKENS: usize = 512;
+
+/// ONNX-runtime mDeBERTa-v3 XNLI verifier.
+///
+/// `session` + `tokenizer` are lazily populated by the first call to
+/// `ensure_loaded`. `new` is eager only for cache_dir create_dir_all
+/// (cheap) so that the rag crate can construct an instance during
+/// `App` boot without paying for the ~280 MB model download.
+pub struct OnnxNliVerifier {
+    model_id: String,
+    cache_dir: PathBuf,
+    session: OnceLock<Session>,
+    tokenizer: OnceLock<Tokenizer>,
+}
+
+impl OnnxNliVerifier {
+    /// Construct a verifier from the user's `Config`. Eagerly resolves
+    /// `cache_dir = config.storage.model_dir/nli/<sanitized-model-id>/`
+    /// and runs `create_dir_all` so the first `score` call can drop
+    /// straight into download + load without re-deriving paths.
+    ///
+    /// Reads `config.models.nli.model` for the HuggingFace model id
+    /// and `config.models.nli.provider` to select the verifier impl —
+    /// only `"onnx"` is implemented in v0.18. The defaults live in
+    /// `kebab-config::NliCfg::defaults` so this path always receives
+    /// a non-empty model id.
+    pub fn new(config: &kebab_config::Config) -> Result<Self> {
+        let provider = config.models.nli.provider.as_str();
+        if provider != "onnx" {
+            anyhow::bail!(
+                "kebab-nli: unsupported provider {provider:?} (only 'onnx' is implemented in v0.18)"
+            );
+        }
+        let model_id = config.models.nli.model.clone();
+
+        // Match kebab-embed-local's two-step expansion: data_dir first,
+        // then model_dir with `{data_dir}` substituted in.
+        let data_dir = expand_path(&config.storage.data_dir, "");
+        let model_dir = expand_path(&config.storage.model_dir, &data_dir.to_string_lossy());
+        let cache_dir = model_dir
+            .join(NLI_CACHE_SUBDIR)
+            .join(sanitize_model_id(&model_id));
+        std::fs::create_dir_all(&cache_dir)
+            .with_context(|| format!("create kebab-nli cache dir {}", cache_dir.display()))?;
+
+        Ok(Self {
+            model_id,
+            cache_dir,
+            session: OnceLock::new(),
+            tokenizer: OnceLock::new(),
+        })
+    }
+
+    /// Download (if needed) + load the ONNX session and tokenizer on
+    /// first call; return cached refs on subsequent calls. Uses two
+    /// `OnceLock`s rather than one because a single `OnceLock<(_, _)>`
+    /// would need to construct both atomically — keeping them split
+    /// lets us short-circuit on the (rare) hit path where only one
+    /// side is missing.
+    ///
+    /// `OnceLock::get_or_try_init` is still unstable (rust-lang/rust#109737)
+    /// so we implement the fallible init by hand: probe `get`, on miss
+    /// compute the value, then `set` it. The race between two threads is
+    /// resolved by `OnceLock::set` — the loser gets `Err`, falls through
+    /// to a second `get`, and reads the winner's value. Each thread that
+    /// races + loses does pay the cost of one redundant download (rare in
+    /// practice: rag boot is single-threaded today), but the cache stays
+    /// consistent.
+    fn ensure_loaded(&self) -> Result<(&Session, &Tokenizer)> {
+        if self.session.get().is_none() {
+            let s = self.load_session()?;
+            let _ = self.session.set(s); // loser of a race: discard local value
+        }
+        if self.tokenizer.get().is_none() {
+            let t = self.load_tokenizer()?;
+            let _ = self.tokenizer.set(t);
+        }
+        // Both OnceLocks are populated at this point; `expect` is a
+        // tighter post-condition than `unwrap_or_else` would be.
+        let session = self.session.get().expect("session populated above");
+        let tokenizer = self.tokenizer.get().expect("tokenizer populated above");
+        Ok((session, tokenizer))
+    }
+
+    /// Build an `hf_hub::api::sync::Api` rooted at `self.cache_dir` and
+    /// fetch `filename` from `self.model_id`. Logs cache hits at INFO
+    /// so a user reading kebab logs can see which artifact source the
+    /// pipeline picked.
+    fn fetch(&self, filename: &str) -> Result<PathBuf> {
+        // Round-1 review N1 fix: `Api::get` triggers download on miss,
+        // so we can't use it as a hit probe. `Cache::get` is fs-only —
+        // returns Some(path) if cached, None otherwise. No network.
+        let repo = hf_hub::Repo::new(self.model_id.clone(), hf_hub::RepoType::Model);
+        let cached = hf_hub::Cache::new(self.cache_dir.clone())
+            .repo(repo.clone())
+            .get(filename)
+            .is_some();
+        if cached {
+            tracing::info!(
+                target: "kebab-nli",
+                model_id = %self.model_id,
+                file = %filename,
+                "NLI artifact cache hit"
+            );
+        } else {
+            tracing::info!(
+                target: "kebab-nli",
+                model_id = %self.model_id,
+                file = %filename,
+                cache_dir = %self.cache_dir.display(),
+                "downloading NLI artifact"
+            );
+        }
+
+        let api = hf_hub::api::sync::ApiBuilder::new()
+            .with_cache_dir(self.cache_dir.clone())
+            .build()
+            .with_context(|| {
+                format!(
+                    "kebab-nli: hf-hub ApiBuilder::build failed (cache_dir={})",
+                    self.cache_dir.display()
+                )
+            })?;
+        api.model(self.model_id.clone())
+            .get(filename)
+            .with_context(|| {
+                format!(
+                    "kebab-nli: hf-hub fetch failed for {filename} (model_id={}, cache_dir={})",
+                    self.model_id,
+                    self.cache_dir.display()
+                )
+            })
+    }
+
+    fn load_session(&self) -> Result<Session> {
+        tracing::info!(
+            target: "kebab-nli",
+            model_id = %self.model_id,
+            "downloading NLI model + tokenizer (first run only)"
+        );
+        let model_path = self.fetch(HF_MODEL_FILE)?;
+        let session = Session::builder()
+            .with_context(|| "kebab-nli: ort Session::builder failed")?
+            .commit_from_file(&model_path)
+            .with_context(|| {
+                format!(
+                    "kebab-nli: ort Session::commit_from_file({}) failed",
+                    model_path.display()
+                )
+            })?;
+        tracing::info!(
+            target: "kebab-nli",
+            model_id = %self.model_id,
+            model_path = %model_path.display(),
+            "NLI model ready"
+        );
+        Ok(session)
+    }
+
+    fn load_tokenizer(&self) -> Result<Tokenizer> {
+        let tokenizer_path = self.fetch(HF_TOKENIZER_FILE)?;
+        let mut tokenizer = Tokenizer::from_file(&tokenizer_path)
+            .map_err(|e| anyhow!("kebab-nli: Tokenizer::from_file({}) failed: {e}", tokenizer_path.display()))?;
+        tokenizer
+            .with_truncation(Some(TruncationParams {
+                max_length: MAX_TOKENS,
+                strategy: TruncationStrategy::OnlyFirst,
+                stride: 0,
+                direction: TruncationDirection::Right,
+            }))
+            .map_err(|e| anyhow!("kebab-nli: Tokenizer::with_truncation failed: {e}"))?;
+        Ok(tokenizer)
+    }
+}
+
+impl NliVerifier for OnnxNliVerifier {
+    fn score(&self, premise: &str, hypothesis: &str) -> Result<NliScores> {
+        // Defense-in-depth: spec §2.3 has the caller skip empty answers,
+        // but a degenerate empty hypothesis here would tokenize to a
+        // [CLS][SEP][SEP] triple that yields a near-uniform softmax —
+        // misleading both faithfulness gate and any future logging.
+        if hypothesis.trim().is_empty() {
+            anyhow::bail!("kebab-nli: empty hypothesis");
+        }
+
+        let (session, tokenizer) = self.ensure_loaded()?;
+
+        let enc = tokenizer
+            .encode((premise, hypothesis), true)
+            .map_err(|e| anyhow!("kebab-nli: tokenizer.encode failed: {e}"))?;
+
+        let ids: Vec<i64> = enc.get_ids().iter().map(|&u| i64::from(u)).collect();
+        let mask: Vec<i64> = enc
+            .get_attention_mask()
+            .iter()
+            .map(|&u| i64::from(u))
+            .collect();
+        let seq_len = ids.len();
+
+        // mDeBERTa-v3 ONNX export expects [batch, seq_len] for both
+        // input_ids and attention_mask. We always feed batch=1.
+        let ids_arr = ndarray::Array2::from_shape_vec((1, seq_len), ids)
+            .with_context(|| "kebab-nli: input_ids ndarray shape build failed")?;
+        let mask_arr = ndarray::Array2::from_shape_vec((1, seq_len), mask)
+            .with_context(|| "kebab-nli: attention_mask ndarray shape build failed")?;
+
+        let outputs = session
+            .run(ort::inputs! {
+                "input_ids" => ids_arr,
+                "attention_mask" => mask_arr,
+            }?)
+            .with_context(|| "kebab-nli: ort Session::run failed")?;
+
+        let logits = outputs["logits"]
+            .try_extract_tensor::<f32>()
+            .with_context(|| "kebab-nli: logits try_extract_tensor::<f32> failed")?;
+
+        // Expected shape [1, 3]. Defensive check — a model swap with a
+        // different head would silently produce wrong scores otherwise.
+        let shape = logits.shape();
+        if shape != [1, LOGITS_LEN] {
+            anyhow::bail!(
+                "kebab-nli: unexpected logits shape {shape:?}, expected [1, {LOGITS_LEN}]"
+            );
+        }
+        let l = [logits[[0, 0]], logits[[0, 1]], logits[[0, 2]]];
+        Ok(NliScores::from_xnli_logits(l))
+    }
+}
+
+/// Make a HuggingFace model id (`"owner/repo"`) into a single
+/// path component safe to use as a directory name. `/` → `_` is
+/// enough for current ids; if more exotic chars appear we'll
+/// widen this then.
+fn sanitize_model_id(s: &str) -> String {
+    s.replace('/', "_")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use kebab_config::Config;
+    use tempfile::TempDir;
+
+    /// Round-1 review N2 fix: redirect Config.storage.{data,model}_dir
+    /// into a tempdir so unit tests don't litter the user's XDG dirs
+    /// with empty `nli/` subdirs.
+    fn tempdir_config() -> (TempDir, Config) {
+        let tmp = TempDir::new().expect("tempdir");
+        let mut cfg = Config::defaults();
+        cfg.storage.data_dir = tmp.path().to_string_lossy().into_owned();
+        cfg.storage.model_dir = "{data_dir}/models".to_string();
+        (tmp, cfg)
+    }
+
+    #[test]
+    fn new_succeeds_on_default_config() {
+        let (_tmp, cfg) = tempdir_config();
+        let v = OnnxNliVerifier::new(&cfg).expect("new should succeed on default config");
+        // cache_dir must include the sanitized model id (no '/').
+        let s = v.cache_dir.to_string_lossy();
+        assert!(s.contains(NLI_CACHE_SUBDIR), "cache_dir lacks nli/: {s}");
+        assert!(
+            !s.contains("Xenova/mDeBERTa"),
+            "cache_dir must sanitize '/' in model id: {s}"
+        );
+        assert!(
+            s.contains("Xenova_mDeBERTa"),
+            "cache_dir should contain sanitized id: {s}"
+        );
+    }
+
+    /// Empty hypothesis takes the defense-in-depth early bail path —
+    /// reaches no model load, so this is a pure unit test (no network).
+    /// Replaces PR-9a's `score_returns_err_in_skeleton` (stub-only).
+    #[test]
+    fn score_empty_hypothesis_returns_err() {
+        let (_tmp, cfg) = tempdir_config();
+        let v = OnnxNliVerifier::new(&cfg).unwrap();
+        let err = v.score("anything", "").expect_err("empty hypothesis must error");
+        assert!(
+            err.to_string().contains("empty hypothesis"),
+            "unexpected error message: {err}"
+        );
+    }
+
+    /// Pins that `config.models.nli.model` flows into `OnnxNliVerifier`
+    /// instead of being silently overridden by a hardcoded constant.
+    /// `model_id` is a private field, but this test lives in the same
+    /// module so it can read it directly — the wiring contract is
+    /// "whatever the user puts in TOML / KEBAB_MODELS_NLI_MODEL is the
+    /// id the verifier uses".
+    #[test]
+    fn new_uses_config_model_id() {
+        let (_tmp, mut cfg) = tempdir_config();
+        cfg.models.nli.model = "custom-org/custom-nli-model".to_string();
+        let v = OnnxNliVerifier::new(&cfg).expect("new should succeed with custom model id");
+        assert_eq!(v.model_id, "custom-org/custom-nli-model");
+        // The custom id also flows into the on-disk cache_dir layout
+        // (sanitized so `/` doesn't escape the namespace).
+        let s = v.cache_dir.to_string_lossy();
+        assert!(
+            s.contains("custom-org_custom-nli-model"),
+            "cache_dir should embed sanitized custom model id: {s}"
+        );
+    }
+
+    /// Pins that a non-`"onnx"` provider value errors out at `new` —
+    /// the field is no longer silently ignored.
+    #[test]
+    fn new_rejects_unsupported_provider() {
+        let (_tmp, mut cfg) = tempdir_config();
+        cfg.models.nli.provider = "candle".to_string();
+        let result = OnnxNliVerifier::new(&cfg);
+        assert!(result.is_err(), "non-onnx provider must error");
+        let msg = result.err().unwrap().to_string();
+        assert!(
+            msg.contains("unsupported provider") && msg.contains("candle"),
+            "error should name the rejected provider: {msg}"
+        );
+    }
+
+    // ── sanitize_model_id pure-fn coverage ────────────────────────────────
+    //
+    // Three tests pin the behavior of the private `sanitize_model_id`
+    // helper. These are orthogonal to the H1 executor tests above
+    // (which cover config-wiring); these cover the transformation
+    // contract of the sanitizer itself.
+
+    #[test]
+    fn sanitize_model_id_replaces_slash_with_underscore() {
+        let input = "Xenova/mDeBERTa-v3-base-xnli-multilingual-nli-2mil7";
+        let expected = "Xenova_mDeBERTa-v3-base-xnli-multilingual-nli-2mil7";
+        assert_eq!(sanitize_model_id(input), expected);
+    }
+
+    #[test]
+    fn sanitize_model_id_is_idempotent_on_already_sanitized() {
+        // Input with no '/' must come back byte-for-byte unchanged.
+        let input = "Xenova_mDeBERTa-v3-base-xnli-multilingual-nli-2mil7";
+        assert_eq!(sanitize_model_id(input), input);
+    }
+
+    #[test]
+    fn sanitize_model_id_leaves_other_chars_untouched() {
+        // Hyphens, digits, dots, and underscores must all pass through
+        // unchanged — only '/' is replaced with '_'.
+        let input = "org_name/model-name_v2.3-alpha";
+        let got = sanitize_model_id(input);
+        assert_eq!(got, "org_name_model-name_v2.3-alpha");
+        assert!(!got.contains('/'), "no slash must remain after sanitize");
+        assert!(got.contains('-'), "hyphens must be preserved");
+        assert!(got.contains('.'), "dots must be preserved");
+        assert!(got.contains('_'), "underscores must be preserved");
+    }
+}

crates/kebab-nli/tests/inference.rs

@@ -0,0 +1,141 @@
+//! Integration tests for `OnnxNliVerifier` against the real
+//! mDeBERTa-v3 XNLI model. Every test is `#[ignore]` — plain
+//! `cargo test -p kebab-nli` skips them; run explicitly with
+//! `cargo test -p kebab-nli --test inference -- --ignored` to
+//! exercise the (slow + network-bound on first run) inference path.
+//!
+//! First test in the file triggers the ~280 MB ONNX + ~16 MB
+//! tokenizer download into `config.storage.model_dir/nli/...`;
+//! subsequent tests hit the OnceLock cache for free.
+
+use kebab_config::Config;
+use kebab_nli::{NliVerifier, OnnxNliVerifier};
+
+/// Test 1: an English statement entails itself with high confidence.
+/// Smoke evidence captured for the PR description's `## 검증` section.
+#[test]
+#[ignore]
+fn en_self_entailment_high_score() {
+    let cfg = Config::defaults();
+    let v = OnnxNliVerifier::new(&cfg).expect("verifier construction");
+    let premise = "Caffeine is a stimulant.";
+    let hypothesis = "Caffeine is a stimulant.";
+    let s = v.score(premise, hypothesis).expect("score should succeed");
+    eprintln!(
+        "[test1 en_self_entailment_high_score] premise={premise:?} hypothesis={hypothesis:?} \
+         scores: entailment={:.4}, neutral={:.4}, contradiction={:.4}",
+        s.entailment, s.neutral, s.contradiction
+    );
+    assert!(
+        s.entailment > 0.8,
+        "expected entailment > 0.8, got {:.4} (full scores: {:?})",
+        s.entailment,
+        s
+    );
+}
+
+/// Test 2: an unrelated chemistry fact does NOT entail the premise.
+/// Entailment should be low — neutral / contradiction wins.
+#[test]
+#[ignore]
+fn en_unrelated_low_entailment() {
+    let cfg = Config::defaults();
+    let v = OnnxNliVerifier::new(&cfg).expect("verifier construction");
+    let premise = "Caffeine is a stimulant.";
+    let hypothesis = "The chemical formula of caffeine is C8H10N4O2.";
+    let s = v.score(premise, hypothesis).expect("score should succeed");
+    eprintln!(
+        "[test2 en_unrelated_low_entailment] \
+         scores: entailment={:.4}, neutral={:.4}, contradiction={:.4}",
+        s.entailment, s.neutral, s.contradiction
+    );
+    // spec §3 PR-9b: "entailment 낮음 — neutral/contradiction 이 winning channel" 의
+    // *spirit* 은 *neutral 이 max* 임. 실측 mDeBERTa 의 noise (entailment≈0.42, neutral≈0.53,
+    // contradiction≈0.05) 에서 두 문장 모두 caffeine 의 *사실* 이라 entailment 가 0.3 미만으로
+    // 떨어지지 않음 — 그러나 neutral 이 winning. multilingual NLI 의 자연스러운 동작.
+    assert!(
+        s.neutral > s.entailment && s.neutral > s.contradiction,
+        "expected neutral to win (no entailment, no contradiction), got {s:?}"
+    );
+}
+
+/// Test 3: Korean entailment. The threshold is intentionally generous
+/// (> 0.5) because cross-lingual XNLI is noisier than English-only.
+#[test]
+#[ignore]
+fn ko_entailment_high_score() {
+    let cfg = Config::defaults();
+    let v = OnnxNliVerifier::new(&cfg).expect("verifier construction");
+    let premise = "사과는 빨갛다.";
+    let hypothesis = "사과는 색이 있다.";
+    let s = v.score(premise, hypothesis).expect("score should succeed");
+    eprintln!(
+        "[test3 ko_entailment_high_score] \
+         scores: entailment={:.4}, neutral={:.4}, contradiction={:.4}",
+        s.entailment, s.neutral, s.contradiction
+    );
+    assert!(
+        s.entailment > 0.5,
+        "expected entailment > 0.5, got {:.4} (full scores: {:?})",
+        s.entailment,
+        s
+    );
+}
+
+/// Test 4: a > 24 000-char premise must not panic. mDeBERTa-v3 is
+/// trained at 512 tokens; the `OnlyFirst` truncation strategy keeps
+/// the premise side from blowing the positional embedding cap.
+#[test]
+#[ignore]
+fn long_premise_truncates_without_panic() {
+    let cfg = Config::defaults();
+    let v = OnnxNliVerifier::new(&cfg).expect("verifier construction");
+    let premise = "foo bar baz ".repeat(2000); // ~24 000 chars
+    let hypothesis = "foo";
+    let s = v
+        .score(&premise, hypothesis)
+        .expect("score should succeed on long premise");
+    eprintln!(
+        "[test4 long_premise_truncates_without_panic] premise_len={} \
+         scores: entailment={:.4}, neutral={:.4}, contradiction={:.4}",
+        premise.len(),
+        s.entailment,
+        s.neutral,
+        s.contradiction
+    );
+    // No NaN / infinity in any channel.
+    for (name, x) in [
+        ("entailment", s.entailment),
+        ("neutral", s.neutral),
+        ("contradiction", s.contradiction),
+    ] {
+        assert!(
+            x.is_finite(),
+            "channel {name} non-finite: {x} (full scores: {s:?})"
+        );
+    }
+    // Softmax invariant — the three channels sum to ~1.
+    let sum = s.entailment + s.neutral + s.contradiction;
+    assert!(
+        (sum - 1.0).abs() < 1e-3,
+        "softmax channels must sum to ~1, got {sum:.6}"
+    );
+}
+
+/// Test 5: an empty hypothesis triggers the defense-in-depth bail
+/// path BEFORE the tokenizer runs. Hits no network — fast, even on
+/// a fresh machine.
+#[test]
+#[ignore]
+fn empty_hypothesis_returns_err() {
+    let cfg = Config::defaults();
+    let v = OnnxNliVerifier::new(&cfg).expect("verifier construction");
+    let err = v
+        .score("anything", "")
+        .expect_err("empty hypothesis must error");
+    let msg = err.to_string();
+    assert!(
+        msg.contains("empty hypothesis"),
+        "expected 'empty hypothesis' in error, got: {msg}"
+    );
+}

crates/kebab-normalize/Cargo.toml

@@ -25,3 +25,6 @@ tracing                   = { workspace = true }
 # default scope, excluding dev-deps) confirms this.
 kebab-parse-md = { path = "../kebab-parse-md" }
 serde_json  = { workspace = true }
+
+[lints]
+workspace = true

crates/kebab-parse-code/Cargo.toml

@@ -22,6 +22,11 @@ tree-sitter-javascript = { workspace = true }
 tree-sitter-go         = { workspace = true }
 tree-sitter-java       = { workspace = true }
 tree-sitter-kotlin-ng  = { workspace = true }
+tree-sitter-c          = { workspace = true }
+tree-sitter-cpp        = { workspace = true }
 
 [dev-dependencies]
 tempfile = { workspace = true }
+
+[lints]
+workspace = true