chore: bump version 0.11.0 → 0.11.1

dogfood semantic cleanup (PR #150) lands: document-centric fetch_span +
assets.workspace_path 'last-registered' semantic explicitly documented.

patch bump 사유: 외부 wire / CLI / config surface 변경 없음. 새 internal
trait method (get_asset) + caller refactor + doc-comment 갱신. twin file
의 fetch_span 잘못 분기 가능성 fix (rare).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

.gitignore

@@ -1,6 +1,6 @@
 .superpowers/
 .worktrees/
 .claude/
-/target/
+/target
 **/*.rs.bk
 Cargo.lock.bak

CLAUDE.md

@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project
 
-Single-user local-first knowledge base + RAG. Rust 2024 workspace, ~20 crates, single binary (`kebab`). All inference is local (Ollama + fastembed + whisper.cpp).
+Single-user local-first knowledge base + RAG. Rust 2024 workspace, ~21 crates, single binary (`kebab`). All inference is local (Ollama + fastembed + whisper.cpp).
 
 The repo's documentation is split by audience — don't duplicate across them:
 
@@ -27,7 +27,7 @@ cargo build --release                          # produces target/release/kebab
 
 `-j 1` for the full workspace test isn't optional: 18 integration-test binaries each link `lance` + `datafusion` + `arrow` + `tantivy` and the parallel link step exhausts memory (linker gets SIGKILL'd, build silently fails partway). Per-crate runs are fine in parallel.
 
-`target/` is 6–10 GB after a fresh build (DataFusion + Lance + fastembed + 18 × test-binary debug info). The dev/test profile is already trimmed (`debug = "line-tables-only"`, `split-debuginfo = "unpacked"` — see workspace `Cargo.toml`). Run `cargo clean` after phase merges if disk pressure shows up; backtraces still resolve to function + line.
+`target/` is 6–10 GB after a fresh build but **balloons to 90+ GB after a few task cycles** (each fb-* batch adds incremental compile artifacts on top of the existing 18 × test-binary debug info). The dev/test profile is already trimmed (`debug = "line-tables-only"`, `split-debuginfo = "unpacked"` — see workspace `Cargo.toml`). Run `cargo clean` **routinely after each merged PR**, not just "if pressure shows up" — disk space is tight and recovery via `cargo clean` is cheap (one re-link per crate on next build). Verified pattern: 92 GB → 0 GB in seconds, backtraces still resolve to function + line.
 
 ## The facade rule
 
@@ -54,13 +54,13 @@ Each task spec lists `Allowed dependencies` and `Forbidden dependencies` per des
 
 - `kebab-core` MUST NOT depend on any other `kebab-*` crate. Domain types only.
 - `kebab-eval`'s `metrics` and `compare` modules MUST NOT import retrieval / embedding / LLM crates directly. The runner is allowed to use `kebab-app`'s facade (P5-1 inheritance — see deviations in that task spec).
-- UI crates (`kebab-cli`, future `kebab-tui`, `kebab-desktop`) MUST NOT import `kebab-store-*` / `kebab-llm-*` / `kebab-parse-*` directly — only `kebab-app`.
+- UI crates (`kebab-cli`, `kebab-mcp`, `kebab-tui`, future `kebab-desktop`) MUST NOT import `kebab-store-*` / `kebab-llm-*` / `kebab-parse-*` directly — only `kebab-app`.
 
 Read the relevant task spec's deps section before adding an import. New crates inherit the same boundary rules.
 
 ## Wire schema v1
 
-All `--json` output carries a `schema_version` field. Current schemas: `ingest_report.v1`, `ingest_progress.v1`, `search_hit.v1`, `answer.v1`, `doctor.v1`, `reset_report.v1`, `eval_run.v1`, `eval_compare.v1`, `list_docs.v1`, `schema.v1`, `error.v1`. Schemas live in `docs/wire-schema/v1/`. The wire shape is the contract for external integrations (Claude Code skills, MCP, etc.); breaking it requires a `*.v2` major bump and parallel-running both for one phase. In `--json` mode, fatal errors emit `error.v1` to stderr as ndjson (non-`--json` mode keeps plain stderr text); exit codes 0/1/2/3 are unchanged — `error.v1.code` provides fine-grained agent branching.
+All `--json` output carries a `schema_version` field. Current schemas: `ingest_report.v1`, `ingest_progress.v1`, `search_hit.v1`, `answer.v1`, `doctor.v1`, `reset_report.v1`, `schema.v1`, `error.v1`, `chunk_inspection.v1`, `citation.v1`, `doc_summary.v1`. Schemas live in `docs/wire-schema/v1/`. The wire shape is the contract for external integrations (Claude Code skills, MCP, etc.); breaking it requires a `*.v2` major bump and parallel-running both for one phase. In `--json` mode, fatal errors emit `error.v1` to stderr as ndjson (non-`--json` mode keeps plain stderr text); exit codes 0/1/2/3 are unchanged — `error.v1.code` provides fine-grained agent branching.
 
 In-tree integration packages live under `integrations/<host>/` — currently `integrations/claude-code/kebab/` (a Claude Code skill that calls `kebab search --json` / `kebab ask --json`). Any wire schema major bump (v1→v2) MUST update each shipped integration in the same PR, same as the version-cascade rule below. Per-user trigger keywords (team / system / acronym) belong in the user's local copy of the skill, not in the repo-shipped frontmatter — keep `integrations/claude-code/kebab/SKILL.md`'s `description` generic.
 
@@ -94,6 +94,7 @@ Release 절차:
 - XDG paths: `~/.config/kebab/`, `~/.local/share/kebab/`, `~/.cache/kebab/`, `~/.local/state/kebab/`.
 - SQLite filename: `kebab.sqlite` (under `data_dir`).
 - Workspace ignore: `.kebabignore` (per directory).
+- `_external/` (under `workspace.root`): single-file / stdin ingest 가 외부 file 을 deterministic 명명 (`<blake3-12>.<ext>`) 으로 copy. 첫 생성 시 `.kebabignore` 자동 append.
 
 The migration from the old `kb` name lives in commits `911fb49 / f1a448d / f9714aa`. If you spot a leftover `kb` reference, treat it as a leftover and fix it (the rename PR sweep covered crates/, docs/, tasks/, README, design doc, fixtures — but workspace root `Cargo.toml` comments needed a follow-up; assume similar misses are possible).
 

Cargo.toml

@@ -22,6 +22,8 @@ members = [
     "crates/kebab-parse-image",
     "crates/kebab-parse-pdf",
     "crates/kebab-tui",
+    "crates/kebab-mcp",
+    "crates/kebab-parse-code",
 ]
 
 [workspace.package]
@@ -29,7 +31,7 @@ edition       = "2024"
 rust-version  = "1.85"
 license       = "MIT OR Apache-2.0"
 repository    = "https://github.com/altair823/kebab"
-version       = "0.3.0"
+version       = "0.11.1"
 
 [workspace.dependencies]
 anyhow       = "1"
@@ -71,10 +73,27 @@ futures      = "0.3"
 # pass; pulled into the workspace deps so future crates can share the
 # same major.
 regex        = "1"
+# MCP (Model Context Protocol) SDK. server + macros + transport-io provide
+# stdio JSON-RPC transport for `kebab-mcp` (p9-fb-30). schemars feature
+# exposes the derive macro used by tool input schemas.
+rmcp         = { version = "1.6", default-features = false, features = ["server", "macros", "transport-io", "schemars"] }
 # Dev-only HTTP mock server for kebab-llm-local Ollama adapter tests. Requires
 # a tokio runtime to host its mock server (the runtime adapter crate stays
 # sync via reqwest::blocking — wiremock is dev-only there).
 wiremock     = "0.6"
+base64       = "0.22"
+# Pure-Rust git library for repo metadata detection (kebab-parse-code).
+# No `git` binary required. Default features include thread-safety + most
+# object-reading capabilities needed for HEAD name + commit SHA queries.
+gix          = { version = "0.70", default-features = false, features = ["revision"] }
+# Rust source parsing for code ingest (kebab-parse-code, p10-1A-2). The
+# chunker stays tree-sitter-free — AST work is parser-side per design §6.3.
+tree-sitter      = "0.26"
+tree-sitter-rust = "0.24"
+# Python / TS / JS grammars for code ingest (kebab-parse-code, p10-1B).
+tree-sitter-python     = "0.25.0"
+tree-sitter-typescript = "0.23.2"
+tree-sitter-javascript = "0.25.0"
 
 # Disk-footprint trim for dev / test builds. Codegen, opt-level, and
 # behavior are unchanged — only DWARF debug info is reduced (line

HANDOFF.md

@@ -20,6 +20,7 @@ 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, tree-sitter-rust, `code-rust-ast-v1` — v0.7.0), **1B 🟡 PR 오픈** (Python `code-python-ast-v1` + TypeScript `code-ts-ast-v1` + JavaScript `code-js-ast-v1` — 3 언어 dogfooding 가능, v0.8.0 대기) |
 
 P0~P5 직렬. P6~P9 P5 이후 병렬 가능.
 
@@ -31,6 +32,14 @@ P0~P5 직렬. P6~P9 P5 이후 병렬 가능.
 
 머지 후 발견된 모든 deviation / hotfix 의 dated 로그는 [tasks/HOTFIXES.md](tasks/HOTFIXES.md). 본 요약은 \"누군가가 인수받을 때 알아두면 시간을 많이 절약하는\" 항목만:
 
+- **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
+- **2026-05-07 fb-28 (main.rs)** — `--readonly` (KEBAB_READONLY) blocks Ingest/IngestFile/IngestStdin/Reset; `--quiet` suppresses progress stderr; error.v1 code: "readonly_mode"
+
+- **2026-05-07 macOS XDG path collision (config 사라지는 버그)** — `dirs` crate 가 macOS 에서 `config_dir()` 과 `data_dir()` 둘 다 `~/Library/Application Support/` 반환 → `reset --data-only` 가 config 파일까지 삭제. Fix: `~/.config`, `~/.local/share`, `~/.cache` 직접 사용. 새 경로: config `~/.config/kebab/`, data `~/.local/share/kebab/`, cache `~/.cache/kebab/`. `Config::load(None)` 이 macOS legacy path 에서 자동 마이그레이션. 자세한 내용: `tasks/HOTFIXES.md`.
+- **2026-05-07 P9 post-도그푸딩 (p9-fb-31)** — `kebab ingest-file <path>` + `kebab ingest-stdin --title <T>` 두 신규 subcommand + MCP tool `ingest_file` / `ingest_stdin` (4 → 6 tool). agent 가 fetch 한 web markdown / 외부 file 을 KB 에 즉시 저장. workspace 외부 file 은 `<workspace.root>/_external/<blake3-12>.<ext>` 로 copy (deterministic 명명 → idempotent). `_external/` 디렉토리 첫 생성 시 `.kebabignore` 자동 append (walk 무한 루프 방지). stdin 은 markdown 전용 + flag (`--title`, `--source-uri`) → frontmatter 자동 prepend. .kebabignore 매치 시 stderr warn 후 진행 (explicit ingest = bypass intent). fb-30 의 v1 read-only MCP 정책 변경 — 첫 mutation tool 도입. spec: `tasks/p9/p9-fb-31-single-file-stdin-ingest.md`. design: `docs/superpowers/specs/2026-05-07-p9-fb-31-single-file-stdin-ingest-design.md`.
+- **2026-05-07 P9 post-도그푸딩 (p9-fb-30)** — `kebab mcp` 신규 subcommand + new crate `kebab-mcp` (lib only) — stdio JSON-RPC server. 4 read-only tool (`search` / `ask` / `schema` / `doctor`) 가 `kebab-app` facade 위에 build. rmcp 1.6 SDK 채택, manual `tools/list` + `tools/call` dispatch (rmcp 의 `#[tool_router]` 매크로 대신). `error_classify` 모듈을 `kebab-cli` → `kebab-app::error_wire` 로 promotion (UI crate 끼리 import 회피, facade 룰 준수). `ErrorV1` 에 `schema_version: String` 필드 추가 — kebab-mcp 의 직접 serialize 경로에서도 wire 정합. `KebabAppState` 가 `(Config, Option<PathBuf>)` carry — doctor tool 의 path-aware behavior 위해. ask + search arm 의 `tokio::task::spawn_blocking` wrap — `OllamaLanguageModel` 의 reqwest blocking client 가 async 안에서 panic 회피. capability flag `mcp_server` `false` → `true`. agent integration MVP 완성 — Claude Code / Cursor / OpenAI Agents 등 host-agnostic 사용 가능. spec: `tasks/p9/p9-fb-30-mcp-server.md`. design: `docs/superpowers/specs/2026-05-07-p9-fb-30-mcp-server-design.md`.
 - **P3-5 / P4-3 `--config` 누락** — `kebab-cli` 가 `--config <path>` 를 honor 하려면 `kebab_app::*_with_config` companion 을 호출해야 함. 두 번 같은 모양으로 회귀했음.
 - **P6-2 OCR 기본 엔진** — spec literal 의 Tesseract 가 시스템 dep 부담으로 거부됨, Ollama vision LM 으로 대체. `OcrEngine` trait 그대로라 future swap 가능.
 - **P6-3 caption** — `GenerateRequest.images` 필드를 `kebab-core::LanguageModel` trait 에 신설. 기존 caller 모두 `images: Vec::new()` 로 마이그레이션.
@@ -80,14 +89,15 @@ P0~P5 직렬. P6~P9 P5 이후 병렬 가능.
 
 P9-2/3/4 는 P9-1 의 parallel-safety contract (sub-state slot 패턴) 덕에 병렬 진행 가능 — 같은 `App` 손대지 않음.
 
-### P9 dogfooding 백로그 (fb-26 ~ fb-42) — 4 minor release 분할
+### P9 dogfooding 백로그 (fb-26 ~ fb-42) — release 분할
 
-2026-05-06 도그푸딩 누적 피드백 + "AI agent 가 kebab 을 쓰게 한다" 궁극 목표용 surface 확장. 17 항목 모두 **status: open + brainstorm 선행 필요**. 각 spec 상단 banner 명시. cascade 영향 / 분량 고려해 한 minor 에 묶지 않고 4 분할. 2026-05-06 renumber — **번호 = release 순서**:
+2026-05-06 도그푸딩 누적 피드백 + "AI agent 가 kebab 을 쓰게 한다" 궁극 목표용 surface 확장. cascade 영향 / 분량 고려해 한 minor 에 묶지 않고 분할.
 
-- **0.3.0 — agent foundation**: fb-26 (log), fb-27 (introspection/error wire), fb-28 (readonly/quiet), fb-29 (daemon), fb-30 (MCP), fb-31 (single-file ingest). agent 통합 MVP.
-- **0.4.0 — agent surface refinement (additive)**: fb-32 (stale), fb-33 (streaming), fb-34 (budget), fb-35 (verbatim fetch), fb-36 (filters), fb-37 (trace/stats).
-- **0.5.0 — RAG quality (cascade 동반)**: fb-38 (score semantics), fb-39 (precision tuning, embedding_version cascade + V00X), fb-40 (fact-grounded, prompt_template_version cascade).
-- **0.6.0 또는 P+**: fb-41 (multi-hop, XL), fb-42 (bulk/rerank, Nice).
+- **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).
 
 각 fb spec frontmatter 의 `target_version` 필드가 source of truth. INDEX.md 의 release subheader 도 동일 grouping.
 

README.md

@@ -7,7 +7,7 @@
 - **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 명시.
 - **빌드 디스크** — 첫 빌드 시 `target/` 가 6–10 GB (Lance + DataFusion + fastembed). 여유 확인.
-- **fastembed 모델** — 첫 `kebab ingest` 시 `multilingual-e5-small` (~470 MB) 자동 다운로드.
+- **fastembed 모델** — 첫 `kebab ingest` 시 `multilingual-e5-large` (~1.3 GB, fb-39b) 자동 다운로드. `config.toml` 에서 `model = "multilingual-e5-small"` 로 명시하면 이전 모델 사용.
 
 ## 설치
 
@@ -34,7 +34,7 @@ cargo install --git https://gitea.altair823.xyz/altair823-org/kebab.git --bin ke
 
 업데이트는 `git pull && cargo install --path crates/kebab-cli --locked --force` 또는 git URL 형식의 경우 `cargo install --git ... --force`.
 
-제거는 `cargo uninstall kebab-cli`. 이 명령은 binary 만 지우고 워크스페이스 데이터는 그대로 남는다. 데이터까지 정리하려면 `kebab reset --all --yes` (config + data + cache + state 4 개 XDG 경로 모두 wipe — **irreversible**, 재시작 시 `kebab init` 다시 실행). 부분 wipe 는 `kebab reset --data-only` (config 보존), `kebab reset --vector-only` (Lance + `embedding_records` 만, 다음 ingest 가 re-embed) 등.
+제거는 `cargo uninstall kebab-cli`. 이 명령은 binary 만 지우고 워크스페이스 데이터는 그대로 남는다. 데이터까지 정리하려면 `kebab reset --all --yes` (config + data + cache + state 4 개 XDG 경로 모두 wipe — **irreversible**, 재시작 시 `kebab init` 다시 실행). 부분 wipe 는 `kebab reset --data-only` (config 보존), `kebab reset --vector-only` (Lance + `embedding_records` 만, 다음 ingest 가 re-embed), **`kebab reset --orphans-only`** (현재 walker scope 밖에 있는 stored doc 만 정리 — `config.workspace.include` 좁히거나 sub-dir 옮긴 후 explicit reconcile; fs 의 file 은 건드리지 않음) 등.
 
 ## Quick start
 
@@ -42,7 +42,7 @@ cargo install --git https://gitea.altair823.xyz/altair823-org/kebab.git --bin ke
 # 첫 실행 — XDG 경로에 데이터 디렉토리 + config.toml 생성
 kebab init
 
-# config 손보고 — workspace.root, 모델 endpoint 등 설정 (지원 형식은 md / png / jpg / pdf 로 고정)
+# config 손보고 — workspace.root, 모델 endpoint 등 설정 (지원 형식: md / png / jpg / pdf / rs / py / ts / js)
 ${EDITOR:-vi} ~/.config/kebab/config.toml
 
 # 색인 (Markdown / 이미지 / PDF 모두 한 번에)
@@ -70,19 +70,51 @@ kebab doctor
 | 명령 | 동작 |
 |------|------|
 | `kebab init` | XDG 경로에 데이터 디렉토리 + config.toml 생성 |
-| `kebab ingest [<path>]` | Markdown / 이미지 / PDF 색인 (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`). 다른 확장자는 자동 skip — `IngestItem.warnings` 에 사유 (`"unsupported media type: .docx"` 등), `IngestReport.skipped_by_extension` 에 카운트 분류, CLI / TUI summary 에 breakdown 표시. |
-| `kebab search --mode {lexical,vector,hybrid} "<query>" [--no-cache]` | 검색. 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 |
+| `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` — 모두 tree-sitter AST chunker). 다른 확장자는 자동 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` / `--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`). |
+| `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 list docs` | 색인된 문서 목록 |
 | `kebab inspect doc <id>` / `kebab inspect chunk <id>` | raw record 보기 |
-| `kebab ask "<query>" [--show-citations / --hide-citations] [--session <id>]` | 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 |
+| `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 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 방지) |
 | `kebab eval run / compare` | golden query 회귀 측정 |
-| `kebab schema [--json]` | introspection — wire schemas / capabilities / models / stats 한 번에. `--json` 은 `schema.v1` wire; 사람 모드는 서식 출력. |
+| `kebab schema [--json]` | introspection — wire schemas / capabilities / models / stats 한 번에. `--json` 은 `schema.v1` wire; 사람 모드는 서식 출력. **stats 에 (p9-fb-37) `media_breakdown` (5 keys: markdown / pdf / image / audio / other) + `lang_breakdown` (BCP-47 코드, NULL 은 literal `"null"`) + `index_bytes` (sqlite + lancedb on-disk 합계) + `stale_doc_count` (`config.search.stale_threshold_days` 초과 doc 수) 추가.** |
+| `kebab ingest-file <path>` | 단일 파일 ingest (workspace 외부 가능). 바이트는 `<workspace.root>/_external/<hash12>.<ext>` 로 copy. `.kebabignore` 매치 시 stderr warn 후 진행 (explicit ingest 가 bypass intent). |
+| `kebab ingest-stdin --title <T> [--source-uri <URI>]` | stdin 의 markdown 본문 ingest. frontmatter (title + source_uri) 자동 prepend. v1 markdown only. |
+| `kebab mcp` | MCP (Model Context Protocol) stdio server. agent host (Claude Code / Cursor / OpenAI Agents) 가 spawn 하여 tool 호출 (`search` / `bulk_search` / `ask` / `fetch` / `schema` / `doctor` / `ingest_file` / `ingest_stdin`). `--config` honor. |
 
 모든 명령에 `--json` 플래그. 출력은 frozen wire schema v1 (`schema_version` 항상 포함, 예: `ingest_report.v1`, `ingest_progress.v1`, `search_hit.v1`, `answer.v1`, `doctor.v1`, `reset_report.v1`, `schema.v1`). `--json` 모드에서 fatal error 는 stderr 에 `error.v1` ndjson 으로 emit (exit code 0/1/2/3 unchanged).
 
+글로벌 플래그: `--readonly` (또는 `KEBAB_READONLY=1`) — 모든 write-path 명령 (`ingest` / `ingest-file` / `ingest-stdin` / `reset`) 을 비활성화, exit 1. `--quiet` — 진행 바 / hint 등 human-readable stderr 억제 (exit code / stdout 출력은 그대로). `KEBAB_PROGRESS=plain` — TTY 가 없는 환경에서도 진행 상황을 plain-text 한 줄씩 stderr 로 출력 (spinner 대신).
+
+### Score 해석 (fb-38)
+
+`search_hit.v1.score` 는 **ranking signal** 이지 confidence 가 아니다. `score_kind` 필드로 의미 선언:
+
+| `score_kind` | 의미 | 범위 |
+|--------------|------|------|
+| `rrf` (hybrid) | RRF normalized | `[0, 1]`, ceiling = 1.0 (양 채널 rank=1) |
+| `bm25` (lexical) | raw BM25 | unbounded (≥ 0) |
+| `cosine` (vector) | cosine sim | `[-1, 1]` |
+
+#### RRF 수식 (hybrid mode)
+
+```
+chunk c 의 raw RRF = Σ_m  1 / (k_rrf + rank_m(c))
+
+여기서 m ∈ {lexical, vector}, k_rrf = config.search.rrf_k (default 60).
+양 채널 모두 rank=1 일 때 raw RRF = 2 / (k_rrf + 1) ≈ 0.0328.
+
+normalize: rrf_score = raw_rrf / (2 / (k_rrf + 1))
+       → rrf_score ∈ [0, 1]. 양쪽 rank=1 → 1.0, 한 쪽만 등장 → ≈ 0.5 천장.
+```
+
+`rrf_score = 0.5` 의 의미: chunk 가 한 채널 (lexical 또는 vector) 에서만 rank 1 로 등장. confidence 50% 가 아님 — RRF 수식의 산술적 천장.
+
+agent 가 trust threshold 가 필요하면 top-level `score` 가 아닌 nested `retrieval.lexical_score` (BM25 raw) / `retrieval.vector_score` (cosine raw) 사용.
+
 ## 논리 아키텍처
 
 ```mermaid
@@ -99,9 +131,9 @@ flowchart TB
     end
 
     subgraph Pipeline["도메인 + 파이프라인"]
-        parse["parse-md / parse-pdf / parse-image"]
-        chunker["chunker (md-heading-v1, pdf-page-v1)"]
-        embedder["embedder (fastembed multilingual-e5-small)"]
+        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)"]
+        embedder["embedder (fastembed multilingual-e5-large)"]
         retriever["retriever (lexical / vector / hybrid RRF)"]
         rag["RAG pipeline"]
     end
@@ -146,7 +178,18 @@ flowchart TB
 
 ## Configuration
 
-- `~/.config/kebab/config.toml` — `kebab init` 가 XDG 경로에 생성. `[workspace]` (root, exclude — include 필드는 제거됨, 지원 형식은 자동 결정), `[storage]`, `[chunking]`, `[models.embedding]`, `[models.llm]`, `[image.ocr]`, `[image.caption]`, `[search]`, `[rag]`, `[ui]` 절. `[ui] theme = "dark" | "light"` 로 TUI 팔레트 선택 (default `"dark"`, 알 수 없는 값은 dark fallback). 옛 config 의 `workspace.include = [...]` 은 silently 무시 + 단발 deprecation warning (p9-fb-25).
+- `~/.config/kebab/config.toml` — `kebab init` 가 XDG 경로에 생성. `[workspace]` (root, exclude — include 필드는 제거됨, 지원 형식은 자동 결정), `[storage]`, `[chunking]`, `[models.embedding]`, `[models.llm]`, `[image.ocr]`, `[image.caption]`, `[search]`, `[rag]`, `[ui]` 절. 
+  - `[models.embedding]` — 
+    - `model` (default `"multilingual-e5-large"`, fb-39b) — 다국어 sentence embedding 모델. 1024-dim. ONNX (~1.3 GB) 첫 실행 시 fastembed cache (`config.storage.model_dir/fastembed/`) 에 자동 다운로드. `"multilingual-e5-small"` (384 dim) 는 backwards-compat 으로 사용 가능 — TOML 에 명시.
+    - `dimensions` (default `1024`) — 모델의 embedding 차원. config 와 LanceDB stored dim 불일치 시 검색 결과 0 건 (orphan table). 모델 변경 시 `kebab reset --vector-only && kebab ingest` 로 vector index 재구축 권장.
+  - `[ui] theme = "dark" | "light"` 로 TUI 팔레트 선택 (default `"dark"`, 알 수 없는 값은 dark fallback). 
+  - `[search] stale_threshold_days = 30` (p9-fb-32) — search hit / RAG citation 의 `stale` 플래그 기준 (default 30 일, `0` 으로 비활성화). 옛 config 의 `workspace.include = [...]` 은 silently 무시 + 단발 deprecation warning (p9-fb-25).
+- `[ingest.code]` (p10-1A-1) — code ingest 의 skip 정책 + chunker 기본값.
+  - `skip_generated_header = true` — 첫 ~512 byte 의 generated marker (`@generated` / `DO NOT EDIT` 등) 감지 시 skip.
+  - `max_file_bytes = 262144` (256 KiB) / `max_file_lines = 5000` — 파일당 cap, 초과 시 skip.
+  - `extra_skip_globs = []` — 사용자 추가 skip 패턴 (`.gitignore` 문법).
+  - `.gitignore` honor: 자동 적용. `.kebabignore` 는 추가 layer. 우선순위: built-in safety net (`node_modules/` / `target/` / `__pycache__/` / `.venv/` / `venv/` / `env/`) > `.gitignore` > `.kebabignore`.
+- `[rag] prompt_template_version` (default `"rag-v2"`) — RAG system prompt version. `"rag-v1"` 은 legacy backwards-compat (사용자 명시 시 유지). v2 강화 규칙: (1) fact 인용 시 [#번호] 앞에 chunk 속 원문 큰따옴표 표기, (2) 학습 지식 동원 금지, (3) 근거 모호 시 "확실하지 않다" 명시.
 - `--config <path>` flag — 임시 워크스페이스 / 격리 테스트 시 사용. CLI / TUI 모두 honor.
 - `KEBAB_*` env — 일부 키 override (`KEBAB_RAG_SCORE_GATE`, `KEBAB_EVAL_GOLDEN`, `KEBAB_COMMIT_HASH` 등).
 - XDG layout: `~/.config/kebab/`, `~/.local/share/kebab/`, `~/.cache/kebab/`, `~/.local/state/kebab/`.
@@ -160,9 +203,28 @@ config 예시는 [docs/SMOKE.md](docs/SMOKE.md) 의 `/tmp/kebab-smoke/config.tom
 
 - **Claude Code skill** — repo 의 [`integrations/claude-code/`](integrations/claude-code/) 가 ship-ready skill. `cp -r integrations/claude-code/kebab ~/.claude/skills/` 한 번이면 새 Claude Code 세션부터 자동 trigger (내부 시스템 / 위키 lookup / 사내 runbook 질문). multi-turn 은 `kebab ask --session <id> --json` 으로 영속 — skill 이 conversation id 관리하면 외부 agent 도 `--repl` 없이 stateful 대화 가능 (p9-fb-18).
 - **Codex / 기타 agent host** — `--json` + frozen wire schema v1 가 stable contract. 동일 패턴으로 ~50줄 wrapper 작성 가능. `integrations/<host>/` 에 추가 PR 환영.
-- **MCP server** — stdio JSON-RPC 로 `kebab-app` facade 1:1 노출.
+- **MCP server** — stdio JSON-RPC 로 `kebab-app` facade 1:1 노출. `kebab mcp` 참조.
 - **HTTP wrapper** — `kebab serve --bind 127.0.0.1:7711` (P+, local-only 가치 신중).
 
+## MCP 사용
+
+`kebab mcp` 가 stdio MCP server. 8 tool: `search` / `bulk_search` (p9-fb-42 — N query 한 번에) / `ask` / `fetch` (p9-fb-35) / `schema` / `doctor` / `ingest_file` / `ingest_stdin`.
+
+Claude Code 빠른 등록 (`~/.claude/mcp.json` 또는 host 동등 위치):
+
+```json
+{
+  "mcpServers": {
+    "kebab": {
+      "command": "kebab",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+자세한 사용법 (Cursor / OpenAI Agents / Copilot CLI config, per-tool 입출력 예시, troubleshooting, multi-turn ask + session 관리, performance / security) — **[docs/mcp-usage.md](docs/mcp-usage.md)** 참조.
+
 ## 비-목표
 
 다중 사용자 SaaS / K8s / 원격 vector DB / enterprise RBAC / 실시간 협업 / 모든 파일 포맷의 완벽한 parsing / agent 임의 파일 수정 / multi-workspace / LLM-as-judge eval / CLIP 시각 embedding / `kebab://` protocol handler — frozen 설계 §11 / §0 참조.

crates/kebab-app/Cargo.toml

@@ -32,6 +32,10 @@ kebab-parse-image = { path = "../kebab-parse-image" }
 # per-asset dispatch (see `ingest_one_asset` PDF branch) and runs the
 # resulting `CanonicalDocument` through `kebab-chunk::PdfPageV1Chunker`.
 kebab-parse-pdf = { path = "../kebab-parse-pdf" }
+# p10-1A-2: Rust AST extractor lives here. App threads it into the
+# per-asset dispatch (see `ingest_one_asset` Code branch) and runs the
+# resulting `CanonicalDocument` through `kebab-chunk::CodeRustAstV1Chunker`.
+kebab-parse-code = { path = "../kebab-parse-code" }
 anyhow               = { workspace = true }
 blake3               = { workspace = true }
 serde                = { workspace = true }
@@ -49,6 +53,11 @@ lru                  = { workspace = true }
 # `" foo "` collapse to one entry. Same crate kebab-normalize +
 # kebab-core already use, no version drift.
 unicode-normalization = "0.1"
+# p9-fb-31: GitignoreBuilder for .kebabignore matching in ingest_file_with_config.
+# Same version as kebab-source-fs (0.4) to avoid duplicate dep versions.
+ignore               = "0.4"
+# p9-fb-34: opaque pagination cursor encodes payload as base64.
+base64               = { workspace = true }
 
 [dev-dependencies]
 rusqlite             = { workspace = true }
@@ -64,3 +73,6 @@ image                = { version = "0.25", default-features = false, features =
 # to the same major (0.32) so byte output is identical between the two
 # fixture surfaces.
 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"] }

crates/kebab-app/src/app.rs

@@ -40,8 +40,8 @@ use anyhow::{Context, Result, anyhow};
 use lru::LruCache;
 
 use kebab_core::{
-    Answer, Embedder, IndexVersion, LanguageModel, Retriever, SearchHit, SearchMode,
-    SearchQuery, VectorStore,
+    Answer, DocumentStore, Embedder, IndexVersion, LanguageModel, Retriever, SearchHit,
+    SearchMode, SearchOpts, SearchQuery, VectorStore,
 };
 use kebab_embed_local::FastembedEmbedder;
 use kebab_llm_local::OllamaLanguageModel;
@@ -50,6 +50,31 @@ use kebab_search::{HybridRetriever, LexicalRetriever, VectorRetriever};
 use kebab_store_sqlite::SqliteStore;
 use kebab_store_vector::LanceVectorStore;
 
+/// p9-fb-34: top-level wrapper around a paginated, budget-limited
+/// search result. Mirrors the wire `search_response.v1` shape.
+///
+/// `next_cursor` is non-null whenever more hits may be reachable —
+/// either the retriever filled the page (more behind it), or the
+/// budget loop popped hits (those popped hits remain fetchable
+/// from `offset + returned`). It is null only when the retriever
+/// returned fewer hits than requested AND nothing was popped — i.e.
+/// the corpus has nothing more for this query.
+///
+/// `truncated` is independent of `next_cursor`: it signals that
+/// the budget loop modified the page (snippet shorten or k pop).
+/// Caller may either widen `max_tokens` (and re-issue the same
+/// query) or follow `next_cursor` (to advance through more hits)
+/// or both.
+#[derive(Clone, Debug)]
+pub struct SearchResponse {
+    pub hits: Vec<SearchHit>,
+    pub next_cursor: Option<String>,
+    pub truncated: bool,
+    /// p9-fb-37: present when caller passed `SearchOpts.trace = true`.
+    /// Consumers that ignore trace should leave this `None`.
+    pub trace: Option<kebab_core::SearchTrace>,
+}
+
 /// Facade state — see module docs for lifetime rules.
 ///
 /// The struct is public so long-lived callers (kb-eval, the future P9
@@ -190,7 +215,21 @@ impl App {
                 corpus_revision = key.corpus_revision,
                 "search served from LRU cache"
             );
-            return Ok(hits.clone());
+            // p9-fb-32: re-stamp staleness on every cache hit. The cache
+            // entry was stamped at insert time against an older `now`
+            // and an older threshold; if either has shifted (config
+            // reload, time passing) the cached `stale: false` may now
+            // be wrong. Re-stamping is cheap (per-hit comparison) and
+            // avoids invalidating the cache on threshold changes.
+            let mut hits = hits.clone();
+            drop(guard);
+            let now = time::OffsetDateTime::now_utc();
+            crate::staleness::mark_stale_in_place(
+                &mut hits,
+                now,
+                self.config.search.stale_threshold_days,
+            );
+            return Ok(hits);
         }
         // Drop the lock before the (potentially slow) retriever call
         // so other in-flight searches can use the cache concurrently.
@@ -205,14 +244,14 @@ impl App {
     /// Used by `--no-cache` CLI invocations and by `search` itself
     /// on cache miss. Identical behavior to the pre-fb-19 `search`.
     pub fn search_uncached(&self, query: SearchQuery) -> Result<Vec<SearchHit>> {
-        match query.mode {
+        let mut hits = match query.mode {
             SearchMode::Lexical => {
                 let lex = LexicalRetriever::with_settings(
                     self.sqlite.clone(),
                     lexical_index_version(&self.config),
                     self.config.search.snippet_chars,
                 );
-                lex.search(&query)
+                lex.search(&query)?
             }
             SearchMode::Vector => {
                 let (emb, vec_store) = self.require_embeddings()?;
@@ -226,7 +265,7 @@ impl App {
                     vec_iv,
                     self.config.search.snippet_chars,
                 );
-                retr.search(&query)
+                retr.search(&query)?
             }
             SearchMode::Hybrid => {
                 let lex = Arc::new(LexicalRetriever::with_settings(
@@ -246,9 +285,232 @@ impl App {
                     self.config.search.snippet_chars,
                 )) as Arc<dyn Retriever>;
                 let hybrid = HybridRetriever::new(&self.config, lex, vec_retr);
-                hybrid.search(&query)
+                hybrid.search(&query)?
+            }
+        };
+        // p9-fb-32: stamp staleness against the freshest possible `now`
+        // and the current threshold. Cheap (per-hit comparison).
+        let now = time::OffsetDateTime::now_utc();
+        crate::staleness::mark_stale_in_place(
+            &mut hits,
+            now,
+            self.config.search.stale_threshold_days,
+        );
+        // p10-1A-2: backfill `code_lang` from the Citation::Code `lang`
+        // field. The search layer (kebab-search) constructs SearchHit with
+        // `code_lang: None`; we own the post-processing here in kebab-app
+        // and can fill it cheaply from data already present in the hit.
+        backfill_code_lang(&mut hits);
+        // p10-1A-2 Task 8b: backfill `repo` from the document's
+        // `Metadata.repo`. Unlike `code_lang`, this cannot be derived from
+        // the Citation alone — it requires a store lookup by `doc_id`.
+        self.backfill_repo(&mut hits);
+        Ok(hits)
+    }
+
+    /// p9-fb-34: budget-aware search facade. Returns hits trimmed to
+    /// `opts.max_tokens` (chars/4 approximation) plus pagination
+    /// metadata. `App::search` is now a thin wrapper that drops the
+    /// metadata for backwards compat.
+    ///
+    /// `SearchResponse.next_cursor` and `truncated` are independent
+    /// signals — see `SearchResponse` doc for details.
+    pub fn search_with_opts(
+        &self,
+        query: SearchQuery,
+        opts: SearchOpts,
+    ) -> Result<SearchResponse> {
+        use crate::cursor;
+
+        let corpus_revision = self.sqlite.corpus_revision().to_string();
+        let offset = match opts.cursor.as_ref() {
+            // p9-fb-34: wrap the typed ErrorV1 in StructuredError so
+            // anyhow carries the structured payload all the way to
+            // `classify` — string formatting here would degrade
+            // `code = "stale_cursor"` to `code = "generic"` on the wire.
+            Some(c) => cursor::decode(c, &corpus_revision)
+                .map_err(|e| anyhow::Error::new(crate::error_wire::StructuredError(e)))?,
+            None => 0,
+        };
+
+        let snippet_chars = opts
+            .snippet_chars
+            .unwrap_or(self.config.search.snippet_chars);
+
+        // Fetch enough to satisfy offset + the requested page. The
+        // retriever returns at most `fetch_k` hits — we then drop
+        // `offset` and keep the next `k_effective`. `k = 0` is
+        // treated as "use config default" so a caller passing through
+        // a default-constructed `SearchQuery` still gets useful work
+        // out of the budget facade.
+        let k_effective = if query.k == 0 {
+            self.config.search.default_k
+        } else {
+            query.k
+        };
+        let fetch_k = offset.saturating_add(k_effective);
+        let fetch_query = SearchQuery {
+            k: fetch_k,
+            ..query.clone()
+        };
+
+        // p9-fb-37: when --trace is requested, bypass the LRU cache and
+        // run through `HybridRetriever::search_with_trace`, which
+        // dispatches by mode internally. Vector / hybrid modes require
+        // embeddings (same as `--mode hybrid`); lexical mode skips
+        // embedder construction via `NoopRetriever` so lexical-only
+        // workspaces (provider = "none") can use `--trace` without
+        // surfacing the "switch to --mode lexical" error.
+        if opts.trace {
+            let lex = Arc::new(LexicalRetriever::with_settings(
+                self.sqlite.clone(),
+                lexical_index_version(&self.config),
+                self.config.search.snippet_chars,
+            )) as Arc<dyn Retriever>;
+            let vec_retr: Arc<dyn Retriever> = if matches!(query.mode, SearchMode::Lexical) {
+                // `HybridRetriever::search_with_trace` never invokes the
+                // vector retriever for `SearchMode::Lexical` (Task 4).
+                // A no-op stand-in lets us avoid the ~470 MB embedder
+                // load when the user only asked for lexical trace.
+                Arc::new(NoopRetriever)
+            } else {
+                let (emb, vec_store) = self.require_embeddings()?;
+                let vec_iv = vector_index_version(emb.as_ref());
+                let vec_dyn: Arc<dyn VectorStore + Send + Sync> = vec_store;
+                let emb_dyn: Arc<dyn Embedder> = emb;
+                Arc::new(VectorRetriever::with_settings(
+                    vec_dyn,
+                    emb_dyn,
+                    self.sqlite.clone(),
+                    vec_iv,
+                    self.config.search.snippet_chars,
+                )) as Arc<dyn Retriever>
+            };
+            let hybrid = HybridRetriever::new(&self.config, lex, vec_retr);
+            let (mut traced_hits, trace) = hybrid.search_with_trace(&fetch_query)?;
+
+            // Stamp staleness — same as search_uncached.
+            let now = time::OffsetDateTime::now_utc();
+            crate::staleness::mark_stale_in_place(
+                &mut traced_hits,
+                now,
+                self.config.search.stale_threshold_days,
+            );
+            // p10-1A-2: backfill code_lang — same as search_uncached.
+            backfill_code_lang(&mut traced_hits);
+            // p10-1A-2 Task 8b: backfill repo — same as search_uncached.
+            self.backfill_repo(&mut traced_hits);
+
+            // Apply offset + k_effective truncation (mirrors non-trace path).
+            let drop_n = offset.min(traced_hits.len());
+            traced_hits.drain(..drop_n);
+            let mut hits: Vec<SearchHit> =
+                traced_hits.into_iter().take(k_effective).collect();
+
+            // Snippet truncation if opts.snippet_chars set (mirror non-trace path).
+            if opts.snippet_chars.is_some() {
+                for h in hits.iter_mut() {
+                    if h.snippet.chars().count() > snippet_chars {
+                        h.snippet = trim_to_chars(&h.snippet, snippet_chars);
+                    }
+                }
+            }
+
+            // Trace path skips the budget loop. Caller will inspect
+            // `hits.len()` and `trace.timing` rather than paginate.
+            return Ok(SearchResponse {
+                hits,
+                next_cursor: None,
+                truncated: false,
+                trace: Some(trace),
+            });
+        }
+
+        // backfill_code_lang + backfill_repo are applied inside `search`
+        // via `search_uncached` — no explicit call needed here. Trace
+        // branch above calls them directly because it bypasses `search`.
+        let mut all_hits = self.search(fetch_query)?;
+
+        // Skip offset.
+        let drop_n = offset.min(all_hits.len());
+        all_hits.drain(..drop_n);
+        let mut hits: Vec<SearchHit> =
+            all_hits.into_iter().take(k_effective).collect();
+
+        // Apply snippet_chars override if shorter than what the
+        // retriever returned (retriever already honored
+        // `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() {
+                if h.snippet.chars().count() > snippet_chars {
+                    h.snippet = trim_to_chars(&h.snippet, snippet_chars);
+                }
             }
         }
+
+        // Budget loop.
+        let mut truncated = false;
+        if let Some(max_tokens) = opts.max_tokens {
+            let max_chars = max_tokens.saturating_mul(4);
+            // Step 1: shorten snippets progressively to a 60-char floor.
+            const SNIPPET_FLOOR: usize = 60;
+            let mut current_snippet_cap = snippet_chars;
+            while estimate_chars(&hits) > max_chars
+                && current_snippet_cap > SNIPPET_FLOOR
+            {
+                current_snippet_cap =
+                    (current_snippet_cap / 2).max(SNIPPET_FLOOR);
+                for h in hits.iter_mut() {
+                    if h.snippet.chars().count() > current_snippet_cap {
+                        h.snippet =
+                            trim_to_chars(&h.snippet, current_snippet_cap);
+                        truncated = true;
+                    }
+                }
+            }
+            // Step 2: pop hits from the end until we fit, but always
+            // keep ≥ 1.
+            while estimate_chars(&hits) > max_chars && hits.len() > 1 {
+                hits.pop();
+                truncated = true;
+            }
+        }
+
+        // p9-fb-34: emit cursor whenever more hits may be reachable.
+        // Three cases produce a non-null cursor:
+        //   (a) returned == k_effective: retriever filled the page; there
+        //       may be more behind it. Speculative — next call may return
+        //       an empty page if nothing remains.
+        //   (b) truncated by k-pop: returned < k_effective because we
+        //       popped hits to fit the budget. Those popped hits live at
+        //       offset+returned..; next call (with same or wider budget)
+        //       resumes from there.
+        //   (c) truncated by snippet-only shrink: returned == k_effective,
+        //       falls under (a). Cursor lets caller paginate; widening
+        //       --max-tokens lets caller re-fetch fuller snippets at the
+        //       same offset.
+        //
+        // No cursor when neither (a) nor (b) applies — i.e. the retriever
+        // returned fewer than k_effective AND we didn't pop. That means
+        // end of available results.
+        let returned = hits.len();
+        let next_cursor = if returned == k_effective || truncated {
+            if offset.saturating_add(returned) > 0 {
+                Some(cursor::encode(offset + returned, &corpus_revision))
+            } else {
+                None
+            }
+        } else {
+            None
+        };
+
+        Ok(SearchResponse {
+            hits,
+            next_cursor,
+            truncated,
+            trace: None,
+        })
     }
 
     /// Run a RAG `ask` against the configured retriever + LLM. Reuses
@@ -531,6 +793,58 @@ impl App {
         }
     }
 
+    /// p10-1A-2 Task 8b: back-fill `SearchHit.repo` from the originating
+    /// document's `Metadata.repo` for every hit whose `repo` field is
+    /// currently `None`. The search layer (kebab-search) constructs hits
+    /// with `repo: None` because it has no store access; we fill it here
+    /// in kebab-app post-retrieval via a per-distinct-`doc_id` store lookup.
+    ///
+    /// Deduplication: a small `HashMap` accumulates the
+    /// `(doc_id → Option<String>)` mapping so each unique document is
+    /// fetched at most once. Search result sets are small (default k ≤ 20),
+    /// so the map overhead is negligible. A `None` entry is cached too
+    /// (document not found or no repo in metadata) to avoid re-querying.
+    ///
+    /// Non-repo documents (markdown, PDF, plain text, code files outside a
+    /// git tree) correctly keep `repo: None` — `Metadata.repo` is already
+    /// `None` for those, so the assignment is a no-op.
+    fn backfill_repo(&self, hits: &mut [SearchHit]) {
+        use std::collections::HashMap;
+        use kebab_core::DocumentId;
+
+        // doc_id → Option<String> where None means "not found / no repo"
+        let mut cache: HashMap<DocumentId, Option<String>> = HashMap::new();
+
+        for hit in hits.iter_mut() {
+            if hit.repo.is_some() {
+                continue;
+            }
+            let repo_val = cache
+                .entry(hit.doc_id.clone())
+                .or_insert_with(|| {
+                    // Deliberately non-aborting: a failed store lookup for
+                    // one hit must not abort the whole search response. Log
+                    // the error so it's observable rather than silently
+                    // dropped (review #140 round 1).
+                    match self.sqlite.get_document(&hit.doc_id) {
+                        Ok(opt) => opt.and_then(|doc| doc.metadata.repo),
+                        Err(e) => {
+                            tracing::warn!(
+                                target: "kebab-app",
+                                doc_id = %hit.doc_id,
+                                error = %e,
+                                "backfill_repo: get_document failed; leaving hit.repo = None"
+                            );
+                            None
+                        }
+                    }
+                });
+            if let Some(r) = repo_val {
+                hit.repo = Some(r.clone());
+            }
+        }
+    }
+
     /// Resolve the embedder + vector store, surfacing the user-friendly
     /// "switch to --mode lexical" error when embeddings are disabled.
     fn require_embeddings(
@@ -564,6 +878,24 @@ fn lexical_index_version(config: &kebab_config::Config) -> IndexVersion {
     IndexVersion(format!("lex:{}", config.chunking.chunker_version))
 }
 
+/// p9-fb-37: stand-in for the vector retriever in the trace path when
+/// `query.mode == SearchMode::Lexical`. `HybridRetriever::search_with_trace`'s
+/// Lexical branch never calls `vector.search()`, so returning an empty
+/// hit list here is safe and lets lexical-only workspaces (embedding
+/// `provider = "none"`) use `--trace` without paying the ~470 MB
+/// embedder load.
+struct NoopRetriever;
+
+impl Retriever for NoopRetriever {
+    fn search(&self, _q: &kebab_core::SearchQuery) -> anyhow::Result<Vec<kebab_core::SearchHit>> {
+        Ok(Vec::new())
+    }
+
+    fn index_version(&self) -> kebab_core::IndexVersion {
+        kebab_core::IndexVersion("noop:trace".into())
+    }
+}
+
 /// Compose a stable `IndexVersion` for the vector retriever. Tracks
 /// `(embedding_model, embedding_version, dimensions)` so a model swap
 /// flags drift via the existing index_version mismatch warning in
@@ -604,6 +936,49 @@ fn blake3_truncate(input: &str) -> u128 {
     u128::from_be_bytes(buf)
 }
 
+/// p9-fb-34: trim `s` to at most `n` Unicode scalar chars. Cheap
+/// alternative to a `.chars().take(n).collect::<String>()` pattern;
+/// reserves capacity proportional to UTF-8 worst case (4 bytes / char)
+/// so the inner push never re-allocates.
+fn trim_to_chars(s: &str, n: usize) -> String {
+    if s.chars().count() <= n {
+        return s.to_string();
+    }
+    let mut out = String::with_capacity(n.saturating_mul(4));
+    for (i, c) in s.chars().enumerate() {
+        if i >= n {
+            break;
+        }
+        out.push(c);
+    }
+    out
+}
+
+/// p9-fb-34: estimate wire JSON char cost of the hit list. Returns 0
+/// per-hit when serialization fails — a SearchHit serialization
+/// failure is an invariant violation; we degrade gracefully (loop
+/// terminates early) rather than panic in the budget loop.
+fn estimate_chars(hits: &[SearchHit]) -> usize {
+    hits.iter()
+        .map(|h| serde_json::to_string(h).map(|s| s.len()).unwrap_or(0))
+        .sum()
+}
+
+/// p10-1A-2: back-fill `SearchHit.code_lang` from `Citation::Code.lang`
+/// for every code hit in the list. The search layer (kebab-search)
+/// constructs hits with `code_lang: None`; we fill it here in kebab-app
+/// post-retrieval so callers see the correct language identifier without
+/// requiring a second SQL query.
+fn backfill_code_lang(hits: &mut [SearchHit]) {
+    for hit in hits.iter_mut() {
+        if let kebab_core::Citation::Code { lang, .. } = &hit.citation {
+            if hit.code_lang.is_none() {
+                hit.code_lang = lang.clone();
+            }
+        }
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -646,3 +1021,59 @@ mod tests {
         assert_ne!(a, d, "different session_id → different hash");
     }
 }
+
+#[cfg(test)]
+mod tests_trace {
+    use super::*;
+    use kebab_core::{SearchMode, SearchOpts, SearchQuery};
+
+    fn open_app_with_temp_dir() -> (tempfile::TempDir, App) {
+        let dir = tempfile::tempdir().unwrap();
+        let mut cfg = kebab_config::Config::defaults();
+        cfg.storage.data_dir = dir.path().to_string_lossy().into_owned();
+        // Bring up migrations.
+        let store = kebab_store_sqlite::SqliteStore::open(&cfg).unwrap();
+        store.run_migrations().unwrap();
+        drop(store);
+        let app = App::open_with_config(cfg).unwrap();
+        (dir, app)
+    }
+
+    #[test]
+    fn search_response_trace_none_when_opts_trace_false() {
+        let (_dir, app) = open_app_with_temp_dir();
+        let q = SearchQuery {
+            text: "x".into(),
+            mode: SearchMode::Lexical,
+            k: 1,
+            filters: Default::default(),
+        };
+        let resp = app.search_with_opts(q, SearchOpts::default()).unwrap();
+        assert!(resp.trace.is_none());
+    }
+
+    #[test]
+    fn search_response_trace_some_when_opts_trace_true_lexical_mode() {
+        // Lexical mode doesn't require embeddings — the trace path
+        // builds HybridRetriever with a `NoopRetriever` stand-in for
+        // the vector side, since `HybridRetriever::search_with_trace`'s
+        // Lexical branch never invokes `vector.search()`. Default
+        // Config has embedding `provider = "none"`, and lexical-mode
+        // trace must succeed under that config (no embedder load).
+        let (_dir, app) = open_app_with_temp_dir();
+        let q = SearchQuery {
+            text: "x".into(),
+            mode: SearchMode::Lexical,
+            k: 1,
+            filters: Default::default(),
+        };
+        let opts = SearchOpts {
+            trace: true,
+            ..Default::default()
+        };
+        let resp = app
+            .search_with_opts(q, opts)
+            .expect("lexical-mode trace must succeed without embeddings");
+        assert!(resp.trace.is_some(), "trace populated when opts.trace=true");
+    }
+}

crates/kebab-app/src/bulk.rs

@@ -0,0 +1,298 @@
+//! p9-fb-42: bulk multi-query facade. Sequential for-loop reusing
+//! one App instance so embedder cold-start + LRU cache amortize
+//! across the N queries.
+
+use anyhow::Context;
+use kebab_core::{
+    BulkSearchItem, BulkSearchSummary, DocumentId, Lang, SearchFilters, SearchHit, SearchMode,
+    SearchOpts, SearchQuery, TrustLevel,
+};
+use serde_json::Value;
+
+use crate::{App, SearchResponse};
+
+/// Hard cap on items per bulk call. Documented in spec — agents that
+/// hit this should batch-split.
+pub const BULK_QUERIES_MAX: usize = 100;
+
+/// p9-fb-42: bulk search facade. Returns `(items, summary)` always
+/// — per-query failures embed `error.v1` JSON in the item rather
+/// than aborting the bulk call. Returns `Err` only for input
+/// validation failures (e.g. >100 queries).
+#[doc(hidden)]
+pub fn bulk_search_with_config(
+    config: kebab_config::Config,
+    raw_items: Vec<Value>,
+) -> anyhow::Result<(Vec<BulkSearchItem>, BulkSearchSummary)> {
+    if raw_items.len() > BULK_QUERIES_MAX {
+        anyhow::bail!(
+            "queries: max {} items, got {}",
+            BULK_QUERIES_MAX,
+            raw_items.len()
+        );
+    }
+
+    let app = App::open_with_config(config).context("kebab-app: open for bulk_search")?;
+
+    let mut results: Vec<BulkSearchItem> = Vec::with_capacity(raw_items.len());
+    let mut succeeded: u32 = 0;
+    let mut failed: u32 = 0;
+
+    for raw in raw_items {
+        let item = run_one(&app, raw);
+        if item.error.is_some() {
+            failed += 1;
+        } else {
+            succeeded += 1;
+        }
+        results.push(item);
+    }
+
+    let summary = BulkSearchSummary {
+        total: succeeded + failed,
+        succeeded,
+        failed,
+    };
+    Ok((results, summary))
+}
+
+fn run_one(app: &App, raw: Value) -> BulkSearchItem {
+    let echo = raw.clone();
+    match parse_one(&raw) {
+        Ok((query, opts)) => match app.search_with_opts(query, opts) {
+            Ok(resp) => BulkSearchItem {
+                query: echo,
+                response: Some(serialize_search_response(&resp)),
+                error: None,
+            },
+            Err(e) => BulkSearchItem {
+                query: echo,
+                response: None,
+                error: Some(error_v1_json("retrieval_error", &format!("{e:#}"), None)),
+            },
+        },
+        Err(msg) => BulkSearchItem {
+            query: echo,
+            response: None,
+            error: Some(error_v1_json("invalid_input", &msg, None)),
+        },
+    }
+}
+
+/// Mirror of `kebab-cli::wire::wire_search_response` — `SearchResponse`
+/// itself is not `Serialize`, so we build the `search_response.v1`-shaped
+/// JSON manually. Each hit also gets `score` promoted from
+/// `retrieval.fusion_score` per §2.2, matching the CLI wire layer.
+fn serialize_search_response(r: &SearchResponse) -> Value {
+    let mut v = serde_json::json!({
+        "schema_version": "search_response.v1",
+        "hits": r.hits.iter().map(serialize_search_hit).collect::<Vec<_>>(),
+        "next_cursor": r.next_cursor,
+        "truncated": r.truncated,
+    });
+    if let Value::Object(ref mut map) = v {
+        let trace_v = match &r.trace {
+            Some(t) => serde_json::to_value(t).unwrap_or(Value::Null),
+            None => Value::Null,
+        };
+        map.insert("trace".to_string(), trace_v);
+    }
+    v
+}
+
+fn serialize_search_hit(h: &SearchHit) -> Value {
+    let mut v = serde_json::to_value(h).unwrap_or(Value::Null);
+    if let Value::Object(ref mut map) = v {
+        if let Some(Value::Object(retrieval)) = map.get("retrieval") {
+            if let Some(score) = retrieval.get("fusion_score").cloned() {
+                map.insert("score".to_string(), score);
+            }
+        }
+        map.insert(
+            "schema_version".to_string(),
+            Value::String("search_hit.v1".to_string()),
+        );
+    }
+    v
+}
+
+fn parse_one(raw: &Value) -> Result<(SearchQuery, SearchOpts), String> {
+    let obj = raw.as_object().ok_or("expected JSON object")?;
+    let text = obj
+        .get("query")
+        .and_then(|v| v.as_str())
+        .ok_or("missing required field: query")?
+        .to_string();
+
+    let mode = match obj.get("mode").and_then(|v| v.as_str()) {
+        None => SearchMode::Hybrid,
+        Some("hybrid") => SearchMode::Hybrid,
+        Some("lexical") => SearchMode::Lexical,
+        Some("vector") => SearchMode::Vector,
+        Some(other) => return Err(format!("invalid mode: {other:?}")),
+    };
+
+    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
+
+    let trust_min = match obj.get("trust_min").and_then(|v| v.as_str()) {
+        None => None,
+        Some("primary") => Some(TrustLevel::Primary),
+        Some("secondary") => Some(TrustLevel::Secondary),
+        Some("generated") => Some(TrustLevel::Generated),
+        Some(other) => return Err(format!("invalid trust_min: {other:?}")),
+    };
+
+    let ingested_after = match obj.get("ingested_after").and_then(|v| v.as_str()) {
+        None => None,
+        Some(s) => Some(
+            time::OffsetDateTime::parse(s, &time::format_description::well_known::Rfc3339)
+                .map_err(|e| format!("invalid ingested_after RFC3339 {s:?}: {e}"))?,
+        ),
+    };
+
+    let media: Vec<String> = obj
+        .get("media")
+        .and_then(|v| v.as_array())
+        .map(|arr| {
+            arr.iter()
+                .filter_map(|x| x.as_str().map(normalize_media_alias))
+                .collect()
+        })
+        .unwrap_or_default();
+
+    let tags_any: Vec<String> = obj
+        .get("tag")
+        .and_then(|v| v.as_array())
+        .map(|arr| {
+            arr.iter()
+                .filter_map(|x| x.as_str().map(String::from))
+                .collect()
+        })
+        .unwrap_or_default();
+
+    let lang = obj
+        .get("lang")
+        .and_then(|v| v.as_str())
+        .map(|s| Lang(s.to_string()));
+
+    let path_glob = obj
+        .get("path_glob")
+        .and_then(|v| v.as_str())
+        .map(String::from);
+
+    let doc_id = obj
+        .get("doc_id")
+        .and_then(|v| v.as_str())
+        .map(|s| DocumentId(s.to_string()));
+
+    let filters = SearchFilters {
+        tags_any,
+        lang,
+        path_glob,
+        trust_min,
+        media,
+        ingested_after,
+        doc_id,
+        repo: vec![],
+        code_lang: vec![],
+    };
+
+    let opts = SearchOpts {
+        max_tokens: obj
+            .get("max_tokens")
+            .and_then(|v| v.as_u64())
+            .map(|n| n as usize),
+        snippet_chars: obj
+            .get("snippet_chars")
+            .and_then(|v| v.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),
+    };
+
+    Ok((
+        SearchQuery {
+            text,
+            mode,
+            k,
+            filters,
+        },
+        opts,
+    ))
+}
+
+fn normalize_media_alias(s: &str) -> String {
+    match s.to_ascii_lowercase().as_str() {
+        "md" => "markdown".to_string(),
+        other => other.to_string(),
+    }
+}
+
+fn error_v1_json(code: &str, message: &str, hint: Option<&str>) -> Value {
+    serde_json::json!({
+        "schema_version": "error.v1",
+        "code": code,
+        "message": message,
+        "hint": hint,
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn open_temp() -> kebab_config::Config {
+        let dir = tempfile::tempdir().unwrap();
+        let mut cfg = kebab_config::Config::defaults();
+        cfg.storage.data_dir = dir.path().to_string_lossy().into_owned();
+        // Bring up migrations so SqliteStore::open_existing succeeds inside App::open.
+        let store = kebab_store_sqlite::SqliteStore::open(&cfg).unwrap();
+        store.run_migrations().unwrap();
+        drop(store);
+        // Leak the tempdir into a static — tests are short-lived; not worth threading.
+        std::mem::forget(dir);
+        cfg
+    }
+
+    #[test]
+    fn empty_input_returns_empty_summary() {
+        let cfg = open_temp();
+        let (items, summary) = bulk_search_with_config(cfg, vec![]).unwrap();
+        assert!(items.is_empty());
+        assert_eq!(summary.total, 0);
+        assert_eq!(summary.succeeded, 0);
+        assert_eq!(summary.failed, 0);
+    }
+
+    #[test]
+    fn over_cap_returns_err() {
+        let cfg = open_temp();
+        let raw: Vec<Value> = (0..101)
+            .map(|_| serde_json::json!({"query": "x"}))
+            .collect();
+        let err = bulk_search_with_config(cfg, raw).unwrap_err();
+        let msg = format!("{err:#}");
+        assert!(msg.contains("max 100"));
+    }
+
+    #[test]
+    fn invalid_item_emits_error_keeps_total_count() {
+        let cfg = open_temp();
+        let raw = vec![
+            serde_json::json!({"query": "ok", "mode": "lexical"}),
+            serde_json::json!({"mode": "lexical"}), // missing required `query`
+        ];
+        let (items, summary) = bulk_search_with_config(cfg, raw).unwrap();
+        assert_eq!(items.len(), 2);
+        assert_eq!(summary.total, 2);
+        // First item: lexical mode against empty corpus succeeds with empty hits.
+        assert!(items[0].error.is_none());
+        // Second item: missing required field.
+        assert!(items[1].error.is_some());
+        assert_eq!(items[1].error.as_ref().unwrap()["code"], "invalid_input");
+    }
+}

crates/kebab-app/src/cursor.rs

@@ -0,0 +1,75 @@
+//! p9-fb-34 opaque pagination cursor.
+//!
+//! Format: base64(JSON({offset: usize, corpus_revision: string})).
+//! Opaque to callers — they MUST NOT decode the contents themselves;
+//! the schema is internal and may change without notice.
+
+use base64::Engine;
+use base64::engine::general_purpose::URL_SAFE_NO_PAD;
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+
+use crate::error_wire::ErrorV1;
+
+#[derive(Serialize, Deserialize)]
+struct Payload {
+    offset: usize,
+    corpus_revision: String,
+}
+
+/// Encode `(offset, corpus_revision)` as an opaque base64 string.
+pub fn encode(offset: usize, corpus_revision: &str) -> String {
+    let payload = Payload {
+        offset,
+        corpus_revision: corpus_revision.to_string(),
+    };
+    let json = serde_json::to_vec(&payload).expect("Payload serializes");
+    URL_SAFE_NO_PAD.encode(&json)
+}
+
+/// Decode an opaque cursor against the expected `corpus_revision`.
+/// Mismatch or malformed input returns an `ErrorV1` with
+/// `code = "stale_cursor"`.
+//
+// p9-fb-34: ErrorV1 is the workspace-wide wire error struct (~200B
+// after monomorphization with Value + String fields). Boxing here
+// would force every call site to deref through a Box for no win —
+// the err-path is rare. Single allow at the function level.
+//
+// p9-fb-34 round-1 review: differentiate the three failure modes
+// (base64 / JSON / revision mismatch) with distinct messages — all
+// keep `code = "stale_cursor"` so the agent's branching logic stays
+// the same, but humans reading the message get a precise hint.
+#[allow(clippy::result_large_err)]
+pub fn decode(s: &str, expected_revision: &str) -> Result<usize, ErrorV1> {
+    let bytes = URL_SAFE_NO_PAD.decode(s.as_bytes()).map_err(|_| ErrorV1 {
+        schema_version: "error.v1".to_string(),
+        code: "stale_cursor".to_string(),
+        message: "cursor is not valid base64. Re-issue search to obtain a fresh cursor."
+            .to_string(),
+        details: Value::Null,
+        hint: None,
+    })?;
+    let payload: Payload = serde_json::from_slice(&bytes).map_err(|_| ErrorV1 {
+        schema_version: "error.v1".to_string(),
+        code: "stale_cursor".to_string(),
+        message: "cursor payload is malformed. Re-issue search to obtain a fresh cursor."
+            .to_string(),
+        details: Value::Null,
+        hint: None,
+    })?;
+    if payload.corpus_revision != expected_revision {
+        return Err(ErrorV1 {
+            schema_version: "error.v1".to_string(),
+            code: "stale_cursor".to_string(),
+            message: format!(
+                "cursor was issued against corpus_revision '{}'; current revision is \
+                 '{}'. Re-issue search to obtain a fresh cursor.",
+                payload.corpus_revision, expected_revision
+            ),
+            details: Value::Null,
+            hint: None,
+        });
+    }
+    Ok(payload.offset)
+}

crates/kebab-app/src/error_wire.rs

@@ -9,19 +9,53 @@
 use serde::{Deserialize, Serialize};
 use serde_json::{Value, json};
 
-use kebab_app::error_signal::{ConfigInvalid, LlmError, NotIndexed};
+use crate::error_signal::{ConfigInvalid, LlmError, NotIndexed};
+
+// p9-fb-34: `stale_cursor` is constructed directly by `cursor::decode`
+// and surfaced through `StructuredError` (an anyhow-friendly wrapper
+// that carries the typed `ErrorV1` payload without lossy string
+// formatting). `classify` short-circuits on it at the top of the
+// function so the typed `code = "stale_cursor"` reaches the wire.
+
+/// Wire schema id for [`ErrorV1`]. Single source of truth — kebab-cli
+/// + kebab-mcp use this via `kebab_app::ERROR_V1_ID`.
+pub const ERROR_V1_ID: &str = "error.v1";
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct ErrorV1 {
+    pub schema_version: String,
     pub code: String,
     pub message: String,
     pub details: Value,
     pub hint: Option<String>,
 }
 
+/// p9-fb-34: typed wrapper around an [`ErrorV1`] so callers that
+/// surface `anyhow::Error` can downcast back to the structured wire
+/// payload instead of losing it to string formatting. Constructed by
+/// the cursor code path (`cursor::decode` → `App::search_with_opts`)
+/// and short-circuited inside [`classify`].
+#[derive(Debug)]
+pub struct StructuredError(pub ErrorV1);
+
+impl std::fmt::Display for StructuredError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "[{}] {}", self.0.code, self.0.message)
+    }
+}
+
+impl std::error::Error for StructuredError {}
+
 pub fn classify(err: &anyhow::Error, verbose: bool) -> ErrorV1 {
+    // p9-fb-34: structured wrapper short-circuits — preserves the
+    // typed payload that callers (cursor::decode) constructed
+    // instead of falling through to `code = "generic"`.
+    if let Some(s) = err.downcast_ref::<StructuredError>() {
+        return s.0.clone();
+    }
     if let Some(s) = err.downcast_ref::<ConfigInvalid>() {
         return ErrorV1 {
+            schema_version: ERROR_V1_ID.to_string(),
             code: "config_invalid".to_string(),
             message: s.to_string(),
             details: json!({
@@ -33,6 +67,7 @@ pub fn classify(err: &anyhow::Error, verbose: bool) -> ErrorV1 {
     }
     if let Some(s) = err.downcast_ref::<NotIndexed>() {
         return ErrorV1 {
+            schema_version: ERROR_V1_ID.to_string(),
             code: "not_indexed".to_string(),
             message: s.to_string(),
             details: json!({
@@ -47,6 +82,7 @@ pub fn classify(err: &anyhow::Error, verbose: bool) -> ErrorV1 {
     }
     if let Some(io) = err.downcast_ref::<std::io::Error>() {
         return ErrorV1 {
+            schema_version: ERROR_V1_ID.to_string(),
             code: "io_error".to_string(),
             message: io.to_string(),
             details: json!({"kind": format!("{:?}", io.kind())}),
@@ -59,6 +95,7 @@ pub fn classify(err: &anyhow::Error, verbose: bool) -> ErrorV1 {
         details = json!({"chain": chain});
     }
     ErrorV1 {
+        schema_version: ERROR_V1_ID.to_string(),
         code: "generic".to_string(),
         message: err.to_string(),
         details,
@@ -69,6 +106,7 @@ pub fn classify(err: &anyhow::Error, verbose: bool) -> ErrorV1 {
 fn classify_llm(s: &LlmError) -> ErrorV1 {
     match s {
         LlmError::Unreachable { endpoint, source } => ErrorV1 {
+            schema_version: ERROR_V1_ID.to_string(),
             code: "model_unreachable".to_string(),
             message: format!("ollama unreachable at {endpoint}"),
             details: json!({
@@ -78,24 +116,28 @@ fn classify_llm(s: &LlmError) -> ErrorV1 {
             hint: Some(format!("ensure `ollama serve` is reachable at {endpoint}")),
         },
         LlmError::ModelNotPulled(model) => ErrorV1 {
+            schema_version: ERROR_V1_ID.to_string(),
             code: "model_not_pulled".to_string(),
             message: format!("ollama model `{model}` is not pulled"),
             details: json!({"model": model}),
             hint: Some(format!("run `ollama pull {model}`")),
         },
         LlmError::Timeout(e) => ErrorV1 {
+            schema_version: ERROR_V1_ID.to_string(),
             code: "timeout".to_string(),
             message: format!("ollama timeout: {e}"),
             details: json!({"source": e.to_string()}),
             hint: Some("increase timeout or check Ollama load".to_string()),
         },
         LlmError::Stream(body) => ErrorV1 {
+            schema_version: ERROR_V1_ID.to_string(),
             code: "generic".to_string(),
             message: format!("ollama HTTP error: {body}"),
             details: json!({"body": body}),
             hint: None,
         },
         LlmError::Malformed(line) => ErrorV1 {
+            schema_version: ERROR_V1_ID.to_string(),
             code: "generic".to_string(),
             message: format!("malformed response line: {line}"),
             details: json!({"line": line}),
@@ -183,4 +225,36 @@ mod tests {
         let v1 = classify(&err, false);
         assert_eq!(v1.code, "io_error");
     }
+
+    #[test]
+    fn stale_cursor_is_not_routed_through_classify() {
+        use anyhow::anyhow;
+        let err: anyhow::Error = anyhow!("stale_cursor: rev mismatch");
+        let v1 = classify(&err, false);
+        // p9-fb-34: stale_cursor is constructed directly by cursor::decode
+        // (single source of truth). classify must not pattern-match on
+        // anyhow string contents — that would create two sources of
+        // truth. The bare anyhow string falls through to "generic".
+        assert_ne!(v1.code, "stale_cursor", "classify must not produce stale_cursor from bare anyhow string");
+    }
+
+    #[test]
+    fn stale_cursor_propagates_through_structured_wrapper() {
+        // p9-fb-34: positive-side contract for the structured-wrapper
+        // path. cursor::decode constructs a typed ErrorV1, the call site
+        // wraps it in `StructuredError`, anyhow carries it, and classify
+        // short-circuits via downcast — preserving the typed code +
+        // message instead of falling through to "generic".
+        let original = ErrorV1 {
+            schema_version: ERROR_V1_ID.to_string(),
+            code: "stale_cursor".to_string(),
+            message: "test stale cursor".to_string(),
+            details: Value::Null,
+            hint: None,
+        };
+        let err: anyhow::Error = anyhow::Error::new(StructuredError(original));
+        let v1 = classify(&err, false);
+        assert_eq!(v1.code, "stale_cursor");
+        assert_eq!(v1.message, "test stale cursor");
+    }
 }

crates/kebab-app/src/external.rs

@@ -0,0 +1,253 @@
+//! Helpers for the `_external/` workspace subdirectory used by
+//! `ingest_file_with_config` and `ingest_stdin_with_config` (p9-fb-31).
+//!
+//! - `ensure_external_dir`: create `<workspace.root>/_external/` if absent.
+//! - `ensure_kebabignore_entry`: append `_external/` to `<workspace.root>/.kebabignore`
+//!   if missing — prevents subsequent `kebab ingest` workspace walks from
+//!   re-walking files that were imported via single-file ingest.
+//! - `copy_to_external`: write bytes to `_external/<blake3-12>.<ext>`, idempotent.
+//! - `inject_frontmatter`: prepend a YAML frontmatter block to a markdown body
+//!   string (used by `ingest_stdin_with_config`).
+
+use std::fs;
+use std::io::Write;
+use std::path::{Path, PathBuf};
+
+use anyhow::{Context, Result};
+
+pub const EXTERNAL_DIR: &str = "_external";
+const KEBABIGNORE_LINE: &str = "_external/";
+
+/// Ensure `<workspace_root>/_external/` exists. Returns the directory path.
+pub fn ensure_external_dir(workspace_root: &Path) -> Result<PathBuf> {
+    let dir = workspace_root.join(EXTERNAL_DIR);
+    fs::create_dir_all(&dir)
+        .with_context(|| format!("create _external dir at {}", dir.display()))?;
+    Ok(dir)
+}
+
+/// Append `_external/` line to `<workspace_root>/.kebabignore` if not already
+/// present. Idempotent — checks for the exact line before appending.
+pub fn ensure_kebabignore_entry(workspace_root: &Path) -> Result<()> {
+    let path = workspace_root.join(".kebabignore");
+    let existing = if path.exists() {
+        fs::read_to_string(&path)
+            .with_context(|| format!("read existing .kebabignore at {}", path.display()))?
+    } else {
+        String::new()
+    };
+    let already = existing
+        .lines()
+        .any(|line| line.trim() == KEBABIGNORE_LINE);
+    if already {
+        return Ok(());
+    }
+    let mut file = fs::OpenOptions::new()
+        .create(true)
+        .append(true)
+        .open(&path)
+        .with_context(|| format!("open .kebabignore for append at {}", path.display()))?;
+    if !existing.is_empty() && !existing.ends_with('\n') {
+        file.write_all(b"\n")?;
+    }
+    writeln!(file, "{}", KEBABIGNORE_LINE)?;
+    Ok(())
+}
+
+/// Copy bytes to `<external_dir>/<blake3-12>.<ext>`. Idempotent — if the
+/// destination file already exists with the expected hash, the existing
+/// file is reused (no second write). Returns the destination path.
+pub fn copy_to_external(
+    external_dir: &Path,
+    bytes: &[u8],
+    ext: &str,
+) -> Result<PathBuf> {
+    let hash = blake3::hash(bytes);
+    let hex = hash.to_hex();
+    let prefix = &hex.as_str()[..12];
+    let filename = format!("{prefix}.{ext}");
+    let dest = external_dir.join(&filename);
+    if !dest.exists() {
+        fs::write(&dest, bytes)
+            .with_context(|| format!("write external file at {}", dest.display()))?;
+    }
+    Ok(dest)
+}
+
+/// Prepend a YAML frontmatter block to a markdown body. Returns the wrapped
+/// markdown string. Errors if `body` already starts with `---` (the user
+/// should use `ingest_file_with_config` for files that already carry
+/// frontmatter).
+///
+/// Internal `yaml_quote` always uses double-quoted YAML form with backslash
+/// escapes for `"` / `\` / control chars — agent-supplied titles with
+/// special characters are safe.
+pub fn inject_frontmatter(
+    body: &str,
+    title: &str,
+    source_uri: Option<&str>,
+) -> Result<String> {
+    let head = body.trim_start();
+    if head.starts_with("---\n") || head.starts_with("---\r\n") || head.starts_with("---\r") {
+        anyhow::bail!(
+            "stdin already has frontmatter; use `kebab ingest-file` for files with metadata"
+        );
+    }
+    let title_yaml = yaml_quote(title);
+    let mut header = String::new();
+    header.push_str("---\n");
+    header.push_str(&format!("title: {title_yaml}\n"));
+    if let Some(uri) = source_uri {
+        let uri_yaml = yaml_quote(uri);
+        header.push_str(&format!("source_uri: {uri_yaml}\n"));
+    }
+    header.push_str("---\n\n");
+    header.push_str(body);
+    Ok(header)
+}
+
+/// YAML-quote a string. Always uses double-quoted form with backslash-escape
+/// for `"` and `\`. Defensive against agent-supplied titles that contain
+/// quotes / control chars.
+fn yaml_quote(s: &str) -> String {
+    let mut out = String::with_capacity(s.len() + 2);
+    out.push('"');
+    for c in s.chars() {
+        match c {
+            '"' => out.push_str("\\\""),
+            '\\' => out.push_str("\\\\"),
+            '\n' => out.push_str("\\n"),
+            '\r' => out.push_str("\\r"),
+            c if (c as u32) < 0x20 => out.push_str(&format!("\\u{:04x}", c as u32)),
+            c => out.push(c),
+        }
+    }
+    out.push('"');
+    out
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use tempfile::tempdir;
+
+    #[test]
+    fn ensure_external_dir_creates_dir() {
+        let dir = tempdir().unwrap();
+        let result = ensure_external_dir(dir.path()).unwrap();
+        assert_eq!(result, dir.path().join("_external"));
+        assert!(result.is_dir());
+    }
+
+    #[test]
+    fn ensure_external_dir_is_idempotent() {
+        let dir = tempdir().unwrap();
+        let _ = ensure_external_dir(dir.path()).unwrap();
+        let result = ensure_external_dir(dir.path()).unwrap();
+        assert!(result.is_dir());
+    }
+
+    #[test]
+    fn ensure_kebabignore_entry_creates_file_with_line() {
+        let dir = tempdir().unwrap();
+        ensure_kebabignore_entry(dir.path()).unwrap();
+        let content = fs::read_to_string(dir.path().join(".kebabignore")).unwrap();
+        assert!(content.lines().any(|l| l.trim() == "_external/"));
+    }
+
+    #[test]
+    fn ensure_kebabignore_entry_appends_to_existing() {
+        let dir = tempdir().unwrap();
+        fs::write(dir.path().join(".kebabignore"), "*.tmp\n").unwrap();
+        ensure_kebabignore_entry(dir.path()).unwrap();
+        let content = fs::read_to_string(dir.path().join(".kebabignore")).unwrap();
+        let lines: Vec<&str> = content.lines().collect();
+        assert!(lines.contains(&"*.tmp"));
+        assert!(lines.contains(&"_external/"));
+    }
+
+    #[test]
+    fn ensure_kebabignore_entry_idempotent() {
+        let dir = tempdir().unwrap();
+        ensure_kebabignore_entry(dir.path()).unwrap();
+        ensure_kebabignore_entry(dir.path()).unwrap();
+        let content = fs::read_to_string(dir.path().join(".kebabignore")).unwrap();
+        let count = content.lines().filter(|l| l.trim() == "_external/").count();
+        assert_eq!(count, 1, "should not duplicate");
+    }
+
+    #[test]
+    fn ensure_kebabignore_entry_handles_missing_trailing_newline() {
+        let dir = tempdir().unwrap();
+        fs::write(dir.path().join(".kebabignore"), "*.tmp").unwrap(); // no \n
+        ensure_kebabignore_entry(dir.path()).unwrap();
+        let content = fs::read_to_string(dir.path().join(".kebabignore")).unwrap();
+        let lines: Vec<&str> = content.lines().collect();
+        assert!(lines.contains(&"*.tmp"));
+        assert!(lines.contains(&"_external/"));
+    }
+
+    #[test]
+    fn copy_to_external_writes_with_hash_prefix_filename() {
+        let dir = tempdir().unwrap();
+        let ext_dir = ensure_external_dir(dir.path()).unwrap();
+        let path = copy_to_external(&ext_dir, b"hello", "md").unwrap();
+        assert!(path.exists());
+        assert!(path.file_name().unwrap().to_string_lossy().ends_with(".md"));
+        let stem = path.file_stem().unwrap().to_string_lossy();
+        assert_eq!(stem.len(), 12);
+    }
+
+    #[test]
+    fn copy_to_external_is_idempotent_for_same_bytes() {
+        let dir = tempdir().unwrap();
+        let ext_dir = ensure_external_dir(dir.path()).unwrap();
+        let p1 = copy_to_external(&ext_dir, b"hello", "md").unwrap();
+        let p2 = copy_to_external(&ext_dir, b"hello", "md").unwrap();
+        assert_eq!(p1, p2);
+    }
+
+    #[test]
+    fn copy_to_external_different_bytes_produce_different_filenames() {
+        let dir = tempdir().unwrap();
+        let ext_dir = ensure_external_dir(dir.path()).unwrap();
+        let p1 = copy_to_external(&ext_dir, b"hello", "md").unwrap();
+        let p2 = copy_to_external(&ext_dir, b"world", "md").unwrap();
+        assert_ne!(p1, p2);
+    }
+
+    #[test]
+    fn inject_frontmatter_basic() {
+        let out = inject_frontmatter("## Body", "Article X", None).unwrap();
+        assert!(out.starts_with("---\ntitle: \"Article X\"\n---\n\n## Body"));
+    }
+
+    #[test]
+    fn inject_frontmatter_with_source_uri() {
+        let out = inject_frontmatter("## Body", "X", Some("https://example.com/x")).unwrap();
+        assert!(out.contains("title: \"X\""));
+        assert!(out.contains("source_uri: \"https://example.com/x\""));
+        assert!(out.contains("\n## Body"));
+    }
+
+    #[test]
+    fn inject_frontmatter_errors_on_existing_frontmatter() {
+        let body = "---\ntitle: Existing\n---\n\n## Body";
+        let err = inject_frontmatter(body, "New", None).unwrap_err();
+        assert!(err.to_string().contains("already has frontmatter"));
+    }
+
+    #[test]
+    fn inject_frontmatter_errors_on_existing_frontmatter_crlf() {
+        let body = "---\r\ntitle: Existing\r\n---\r\n\r\n## Body";
+        let err = inject_frontmatter(body, "New", None).unwrap_err();
+        assert!(err.to_string().contains("already has frontmatter"));
+    }
+
+    #[test]
+    fn yaml_quote_escapes_quotes_and_backslashes() {
+        assert_eq!(yaml_quote("hello \"world\""), "\"hello \\\"world\\\"\"");
+        assert_eq!(yaml_quote("path\\to"), "\"path\\\\to\"");
+        assert_eq!(yaml_quote("line\nbreak"), "\"line\\nbreak\"");
+    }
+}

crates/kebab-app/src/fetch.rs

@@ -0,0 +1,449 @@
+//! p9-fb-35 verbatim fetch implementation.
+//!
+//! [`App::fetch`] is the facade entry point. It dispatches on
+//! [`FetchQuery`] variants:
+//!
+//! - `Chunk(id)` — return the chunk row from `chunks.text`, optionally
+//!   with ±N surrounding chunks (`FetchOpts::context`).
+//! - `Doc(id)` — return the entire document re-serialized to markdown.
+//!   (Implemented in Task 4.)
+//! - `Span { doc_id, line_start, line_end }` — return a contiguous line
+//!   slice. (Implemented in Task 5.)
+//!
+//! Errors are surfaced as [`StructuredError`] (anyhow-friendly wrapper
+//! around `ErrorV1`) so the CLI / MCP wire layer's `classify` keeps the
+//! typed `code` (`chunk_not_found` / `doc_not_found` /
+//! `span_not_supported`) instead of falling through to `code =
+//! "generic"`.
+
+use anyhow::Result;
+use time::OffsetDateTime;
+
+use kebab_core::{
+    Block, CanonicalDocument, Chunk, ChunkId, DocumentId, DocumentStore, FetchKind, FetchOpts,
+    FetchQuery, FetchResult,
+};
+
+use crate::App;
+use crate::error_wire::{ERROR_V1_ID, ErrorV1, StructuredError};
+use crate::staleness::compute_stale;
+
+impl App {
+    /// p9-fb-35: verbatim fetch facade. Returns text from
+    /// `chunks.text` / `CanonicalDocument` based on the requested
+    /// mode. Errors surface as `StructuredError(ErrorV1)` with one
+    /// of `chunk_not_found` / `doc_not_found` / `span_not_supported`
+    /// so the wire-layer classifier preserves the typed code.
+    pub fn fetch(&self, query: FetchQuery, opts: FetchOpts) -> Result<FetchResult> {
+        match query {
+            FetchQuery::Chunk(id) => fetch_chunk(self, id, opts),
+            FetchQuery::Doc(id) => fetch_doc(self, id, opts),
+            FetchQuery::Span {
+                doc_id,
+                line_start,
+                line_end,
+            } => fetch_span(self, doc_id, line_start, line_end, opts),
+        }
+    }
+}
+
+fn fetch_chunk(app: &App, id: ChunkId, opts: FetchOpts) -> Result<FetchResult> {
+    let target = <kebab_store_sqlite::SqliteStore as DocumentStore>::get_chunk(&app.sqlite, &id)?
+        .ok_or_else(|| {
+            anyhow::Error::new(StructuredError(ErrorV1 {
+                schema_version: ERROR_V1_ID.to_string(),
+                code: "chunk_not_found".to_string(),
+                message: format!("chunk_id '{}' not found", id.0),
+                details: serde_json::Value::Null,
+                hint: None,
+            }))
+        })?;
+
+    let doc_id = target.doc_id.clone();
+    let doc =
+        <kebab_store_sqlite::SqliteStore as DocumentStore>::get_document(&app.sqlite, &doc_id)?
+            .ok_or_else(|| {
+                anyhow::Error::new(StructuredError(ErrorV1 {
+                    schema_version: ERROR_V1_ID.to_string(),
+                    code: "doc_not_found".to_string(),
+                    message: format!(
+                        "doc_id '{}' (parent of chunk '{}') not found",
+                        doc_id.0, id.0
+                    ),
+                    details: serde_json::Value::Null,
+                    hint: None,
+                }))
+            })?;
+
+    let (context_before, context_after) = match opts.context {
+        Some(n) if n > 0 => surrounding_chunks(app, &doc_id, &id, n)?,
+        _ => (Vec::new(), Vec::new()),
+    };
+
+    let now = OffsetDateTime::now_utc();
+    let stale = compute_stale(
+        doc_metadata_updated_at(&doc),
+        now,
+        app.config.search.stale_threshold_days,
+    );
+
+    Ok(FetchResult {
+        kind: FetchKind::Chunk,
+        doc_id: doc.doc_id.clone(),
+        doc_path: doc.workspace_path.clone(),
+        indexed_at: doc_metadata_updated_at(&doc),
+        stale,
+        chunk: Some(target),
+        context_before,
+        context_after,
+        text: None,
+        line_start: None,
+        line_end: None,
+        effective_end: None,
+        truncated: false,
+    })
+}
+
+fn fetch_doc(app: &App, id: DocumentId, opts: FetchOpts) -> Result<FetchResult> {
+    let doc = <kebab_store_sqlite::SqliteStore as DocumentStore>::get_document(&app.sqlite, &id)?
+        .ok_or_else(|| {
+            anyhow::Error::new(StructuredError(ErrorV1 {
+                schema_version: ERROR_V1_ID.to_string(),
+                code: "doc_not_found".to_string(),
+                message: format!("doc_id '{}' not found", id.0),
+                details: serde_json::Value::Null,
+                hint: None,
+            }))
+        })?;
+
+    let mut text = fmt_canonical_to_markdown(&doc);
+    let mut truncated = false;
+    if let Some(max_tokens) = opts.max_tokens {
+        let max_chars = max_tokens.saturating_mul(4);
+        if text.chars().count() > max_chars {
+            text = trim_to_chars(&text, max_chars);
+            truncated = true;
+        }
+    }
+
+    let now = OffsetDateTime::now_utc();
+    let stale = compute_stale(
+        doc_metadata_updated_at(&doc),
+        now,
+        app.config.search.stale_threshold_days,
+    );
+
+    Ok(FetchResult {
+        kind: FetchKind::Doc,
+        doc_id: doc.doc_id.clone(),
+        doc_path: doc.workspace_path.clone(),
+        indexed_at: doc_metadata_updated_at(&doc),
+        stale,
+        chunk: None,
+        context_before: Vec::new(),
+        context_after: Vec::new(),
+        text: Some(text),
+        line_start: None,
+        line_end: None,
+        effective_end: None,
+        truncated,
+    })
+}
+
+/// p9-fb-35: trim string to N chars (Unicode-safe). Mirrors fb-34's
+/// helper at `crates/kebab-app/src/app.rs` — kept local to avoid
+/// re-exporting an internal helper.
+fn trim_to_chars(s: &str, n: usize) -> String {
+    if s.chars().count() <= n {
+        return s.to_string();
+    }
+    let mut out = String::with_capacity(n * 4);
+    for (i, c) in s.chars().enumerate() {
+        if i >= n {
+            break;
+        }
+        out.push(c);
+    }
+    out
+}
+
+fn fetch_span(
+    app: &App,
+    id: DocumentId,
+    line_start: u32,
+    line_end: u32,
+    opts: FetchOpts,
+) -> Result<FetchResult> {
+    let doc = <kebab_store_sqlite::SqliteStore as DocumentStore>::get_document(&app.sqlite, &id)?
+        .ok_or_else(|| {
+            anyhow::Error::new(StructuredError(ErrorV1 {
+                schema_version: ERROR_V1_ID.to_string(),
+                code: "doc_not_found".to_string(),
+                message: format!("doc_id '{}' not found", id.0),
+                details: serde_json::Value::Null,
+                hint: None,
+            }))
+        })?;
+
+    // Reject line-incompatible media types (PDF / audio). `SourceType`
+    // (markdown / note / paper / reference / inbox) is the *user-facing*
+    // category, not the rendering format — the actual byte-level format
+    // lives on the source `RawAsset.media_type`. Look it up via
+    // doc.source_asset_id (PRIMARY KEY) so twin files (identical content
+    // at different paths) always read *this* document's own asset row,
+    // not whichever twin last wrote `assets.workspace_path`.
+    if let Some(asset) = <kebab_store_sqlite::SqliteStore as DocumentStore>::get_asset(
+        &app.sqlite,
+        &doc.source_asset_id,
+    )? {
+        if matches!(
+            asset.media_type,
+            kebab_core::MediaType::Pdf | kebab_core::MediaType::Audio(_)
+        ) {
+            return Err(anyhow::Error::new(StructuredError(ErrorV1 {
+                schema_version: ERROR_V1_ID.to_string(),
+                code: "span_not_supported".to_string(),
+                message: format!(
+                    "doc '{}' has media_type {:?}; line-based span fetch unsupported. \
+                     Use `fetch chunk` or `fetch doc` instead.",
+                    id.0, asset.media_type
+                ),
+                details: serde_json::Value::Null,
+                hint: Some("kind = chunk or kind = doc instead".to_string()),
+            })));
+        }
+    }
+
+    if line_start == 0 || line_end == 0 || line_end < line_start {
+        return Err(anyhow::Error::new(StructuredError(ErrorV1 {
+            schema_version: ERROR_V1_ID.to_string(),
+            code: "invalid_input".to_string(),
+            message: format!(
+                "line_start ({line_start}) and line_end ({line_end}) must be 1-based with start <= end"
+            ),
+            details: serde_json::Value::Null,
+            hint: None,
+        })));
+    }
+
+    let full = fmt_canonical_to_markdown(&doc);
+    let lines: Vec<&str> = full.lines().collect();
+    let total = lines.len() as u32;
+
+    // p9-fb-35 round-1 review fix: empty / out-of-range request must
+    // not slice. Returning empty text + `effective_end = line_start - 1`
+    // lets the caller detect "no lines fetched" via
+    // `text.is_empty() && effective_end < line_start`. `truncated`
+    // stays false because line-range clamp is NOT a budget event —
+    // budget-driven truncation is the only thing `truncated` signals.
+    if total == 0 || line_start > total {
+        let now = OffsetDateTime::now_utc();
+        let stale = compute_stale(
+            doc_metadata_updated_at(&doc),
+            now,
+            app.config.search.stale_threshold_days,
+        );
+        return Ok(FetchResult {
+            kind: FetchKind::Span,
+            doc_id: doc.doc_id.clone(),
+            doc_path: doc.workspace_path.clone(),
+            indexed_at: doc_metadata_updated_at(&doc),
+            stale,
+            chunk: None,
+            context_before: Vec::new(),
+            context_after: Vec::new(),
+            text: Some(String::new()),
+            line_start: Some(line_start),
+            line_end: Some(line_end),
+            // saturating_sub: when line_start = 1 we end at 0, signaling
+            // "no lines fetched" without underflowing u32.
+            effective_end: Some(line_start.saturating_sub(1)),
+            truncated: false,
+        });
+    }
+
+    let effective_end_raw = line_end.min(total);
+    let lo = (line_start - 1) as usize;
+    let hi = effective_end_raw as usize;
+    let mut text = lines[lo..hi].join("\n");
+
+    // p9-fb-35 round-1 review fix: `truncated` is reserved for
+    // budget-driven truncation only. Line-range clamp (line_end >
+    // total) is signaled via `effective_end < line_end`, not via
+    // `truncated`.
+    let mut truncated = false;
+    let mut effective_end = effective_end_raw;
+    if let Some(max_tokens) = opts.max_tokens {
+        let max_chars = max_tokens.saturating_mul(4);
+        if text.chars().count() > max_chars {
+            text = trim_to_chars(&text, max_chars);
+            truncated = true;
+            let kept = text.lines().count() as u32;
+            effective_end = (line_start - 1) + kept;
+        }
+    }
+
+    let now = OffsetDateTime::now_utc();
+    let stale = compute_stale(
+        doc_metadata_updated_at(&doc),
+        now,
+        app.config.search.stale_threshold_days,
+    );
+
+    Ok(FetchResult {
+        kind: FetchKind::Span,
+        doc_id: doc.doc_id.clone(),
+        doc_path: doc.workspace_path.clone(),
+        indexed_at: doc_metadata_updated_at(&doc),
+        stale,
+        chunk: None,
+        context_before: Vec::new(),
+        context_after: Vec::new(),
+        text: Some(text),
+        line_start: Some(line_start),
+        line_end: Some(line_end),
+        effective_end: Some(effective_end),
+        truncated,
+    })
+}
+
+/// p9-fb-35: list chunks for a document in ordinal order, return
+/// `(before, after)` slices around the target chunk_id. `n` caps each
+/// side independently — the worst case is `2n` total neighbors when
+/// the target sits in the middle of the doc.
+fn surrounding_chunks(
+    app: &App,
+    doc_id: &DocumentId,
+    target: &ChunkId,
+    n: u32,
+) -> Result<(Vec<Chunk>, Vec<Chunk>)> {
+    let chunks = list_chunks_in_order(app, doc_id)?;
+    let target_idx = chunks
+        .iter()
+        .position(|c| c.chunk_id == *target)
+        .ok_or_else(|| anyhow::anyhow!("chunk not found in doc chunk list"))?;
+    let n = n as usize;
+    let lo = target_idx.saturating_sub(n);
+    let hi = target_idx
+        .saturating_add(n)
+        .saturating_add(1)
+        .min(chunks.len());
+    let before: Vec<Chunk> = chunks[lo..target_idx].to_vec();
+    let after: Vec<Chunk> = chunks[target_idx + 1..hi].to_vec();
+    Ok((before, after))
+}
+
+/// p9-fb-35: chunks have no explicit ordinal column, so the underlying
+/// helper sorts by `(created_at, chunk_id)` which matches insertion
+/// order produced by the chunker (deterministic). The actual SQL lives
+/// inside `kebab-store-sqlite` (`SqliteStore::list_chunk_ids_for_doc`)
+/// to keep the facade crate free of direct rusqlite usage.
+fn list_chunks_in_order(app: &App, doc_id: &DocumentId) -> Result<Vec<Chunk>> {
+    let chunk_ids = app.sqlite.list_chunk_ids_for_doc(doc_id)?;
+    let mut out: Vec<Chunk> = Vec::with_capacity(chunk_ids.len());
+    for cid in chunk_ids {
+        if let Some(chunk) =
+            <kebab_store_sqlite::SqliteStore as DocumentStore>::get_chunk(&app.sqlite, &cid)?
+        {
+            out.push(chunk);
+        }
+    }
+    Ok(out)
+}
+
+fn doc_metadata_updated_at(doc: &CanonicalDocument) -> OffsetDateTime {
+    doc.metadata.updated_at
+}
+
+/// p9-fb-35: serialize a `CanonicalDocument` back to markdown. Best-
+/// effort round-trip — inline-styled spans (Strong/Emph children)
+/// flatten to plain text via the already-flattened `TextBlock.text`
+/// field. Good enough for an agent reading verbatim context. Used by
+/// Task 4 (doc mode) and Task 5 (span mode).
+pub(crate) fn fmt_canonical_to_markdown(doc: &CanonicalDocument) -> String {
+    let mut out = String::with_capacity(1024);
+    for (i, block) in doc.blocks.iter().enumerate() {
+        if i > 0 {
+            out.push_str("\n\n");
+        }
+        match block {
+            Block::Heading(h) => {
+                let level = h.level.clamp(1, 6) as usize;
+                for _ in 0..level {
+                    out.push('#');
+                }
+                out.push(' ');
+                out.push_str(&h.text);
+            }
+            Block::Paragraph(t) => out.push_str(&t.text),
+            Block::Quote(t) => {
+                // Prefix every line with `> ` so block-quote round-trips.
+                for (li, line) in t.text.split('\n').enumerate() {
+                    if li > 0 {
+                        out.push('\n');
+                    }
+                    out.push_str("> ");
+                    out.push_str(line);
+                }
+            }
+            Block::List(l) => {
+                for (idx, item) in l.items.iter().enumerate() {
+                    if idx > 0 {
+                        out.push('\n');
+                    }
+                    if l.ordered {
+                        out.push_str(&format!("{}. {}", idx + 1, item.text));
+                    } else {
+                        out.push_str(&format!("- {}", item.text));
+                    }
+                }
+            }
+            Block::Code(c) => {
+                out.push_str("```");
+                if let Some(lang) = &c.lang {
+                    out.push_str(lang);
+                }
+                out.push('\n');
+                out.push_str(&c.code);
+                if !c.code.ends_with('\n') {
+                    out.push('\n');
+                }
+                out.push_str("```");
+            }
+            Block::Table(t) => {
+                out.push_str(&t.headers.join(" | "));
+                out.push('\n');
+                // Markdown table separator — N copies of `---|` is
+                // acceptable for a verbatim re-serialization (renderer
+                // tolerates trailing pipe).
+                out.push_str(&"---|".repeat(t.headers.len()));
+                for row in &t.rows {
+                    out.push('\n');
+                    out.push_str(&row.join(" | "));
+                }
+            }
+            Block::ImageRef(img) => {
+                out.push_str(&format!("![{}]({})", img.alt, img.src));
+            }
+            Block::AudioRef(_a) => {
+                // Canonical doc carries the transcript on AudioRefBlock,
+                // but markdown has no native audio embed. Emit a stub
+                // marker so the agent sees something ran here.
+                out.push_str("(audio reference)");
+            }
+        }
+    }
+    out
+}
+
+/// p9-fb-35: free-function entry for CLI / MCP. Mirrors the
+/// `*_with_config` pattern documented in the kebab-app crate root —
+/// `kebab-cli` calls this so a `--config <path>` flag is honored.
+#[doc(hidden)]
+pub fn fetch_with_config(
+    config: kebab_config::Config,
+    query: FetchQuery,
+    opts: FetchOpts,
+) -> Result<FetchResult> {
+    App::open_with_config(config)?.fetch(query, opts)
+}

crates/kebab-app/src/ingest_progress.rs

@@ -96,6 +96,7 @@ pub fn media_label(media: &kebab_core::MediaType) -> &'static str {
         kebab_core::MediaType::Pdf => "pdf",
         kebab_core::MediaType::Image(_) => "image",
         kebab_core::MediaType::Audio(_) => "audio",
+        kebab_core::MediaType::Code(_) => "code",
         kebab_core::MediaType::Other(_) => "other",
     }
 }
@@ -148,6 +149,7 @@ mod tests {
             media_label(&MediaType::Audio(kebab_core::AudioType::Wav)),
             "audio"
         );
+        assert_eq!(media_label(&MediaType::Code("rust".into())), "code");
         assert_eq!(media_label(&MediaType::Other("x".into())), "other");
     }
 

crates/kebab-app/src/lib.rs

@@ -39,33 +39,45 @@ use std::sync::Arc;
 use anyhow::{Context, anyhow};
 use serde::{Deserialize, Serialize};
 
-use kebab_chunk::{MdHeadingV1Chunker, PdfPageV1Chunker};
+use kebab_chunk::{CodeJsAstV1Chunker, CodePythonAstV1Chunker, CodeRustAstV1Chunker, CodeTsAstV1Chunker, MdHeadingV1Chunker, PdfPageV1Chunker};
 use kebab_core::{
     Answer, Block, CanonicalDocument, Chunk, ChunkId, ChunkPolicy, ChunkerVersion, Chunker,
     DocFilter, DocSummary, DocumentId, DocumentStore, Embedder, EmbeddingInput,
     EmbeddingKind, ExtractContext, Extractor, IngestReport, Lang, LanguageModel, MediaType,
-    ParserVersion, RawAsset, SearchHit, SearchQuery, SourceConnector, SourceScope,
+    ParserVersion, RawAsset, SearchHit, SearchQuery, SourceScope,
     SourceUri, VectorRecord, VectorStore,
 };
 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::{JavascriptAstExtractor, PythonAstExtractor, RustAstExtractor, TypescriptAstExtractor};
 use kebab_parse_pdf::PdfTextExtractor;
 use kebab_parse_md::{BodyHints, parse_blocks, parse_frontmatter};
 use kebab_source_fs::FsSourceConnector;
 
 mod app;
+mod bulk;
+pub mod cursor;
 pub mod doctor_signal;
 pub mod error_signal;
+pub mod error_wire;
+pub mod external;
+pub mod fetch;
 pub mod ingest_progress;
 pub mod logging;
 pub mod reset;
 pub mod schema;
+mod staleness;
 
-pub use app::App;
+pub use app::{App, SearchResponse};
 pub use ingest_progress::{AggregateCounts, IngestEvent, render_skipped_breakdown};
-pub use reset::{ResetReport, ResetScope};
+pub use reset::{ResetReport, ResetScope, enumerate_orphans};
+pub use error_wire::{ERROR_V1_ID, ErrorV1, StructuredError, classify};
+pub use fetch::fetch_with_config;
+#[doc(hidden)]
+pub use bulk::{BULK_QUERIES_MAX, bulk_search_with_config};
 pub use schema::{Capabilities, Models, SCHEMA_V1_ID, SchemaV1, Stats, WireBlock, schema_with_config};
+pub use staleness::{compute_stale, mark_stale_in_place};
 
 /// p9-fb-25: sentinel for files without an extension in
 /// `IngestReport.skipped_by_extension` keys + `IngestItem.warnings`
@@ -80,7 +92,7 @@ pub const NO_EXT_SENTINEL: &str = "<no-ext>";
 /// `use kebab_app::AskOpts` keeps working without churn. The struct gained
 /// a `stream_sink` field in P4-3; non-streaming callers (kb-cli today)
 /// pass `stream_sink: None`.
-pub use kebab_rag::AskOpts;
+pub use kebab_rag::{AskOpts, StreamEvent};
 
 #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
 pub struct DoctorReport {
@@ -294,8 +306,8 @@ pub fn ingest_with_config_opts(
     );
     let connector = FsSourceConnector::new(&app.config)
         .context("kb-app::ingest: build FsSourceConnector")?;
-    let assets = connector
-        .scan(&scope)
+    let (assets, fs_skips) = connector
+        .scan_with_skips(&scope)
         .context("kb-app::ingest: scan workspace")?;
     crate::ingest_progress::emit(
         progress,
@@ -363,6 +375,28 @@ pub fn ingest_with_config_opts(
         .map(|d| d.doc_id.0)
         .collect();
 
+    // Dogfood: post-walker sweep to remove stored docs whose source
+    // file has been deleted from the filesystem. Must run BEFORE the
+    // per-asset loop so the loop's New/Updated labelling is based on
+    // the post-purge store state (the purged doc_ids won't be in
+    // `existing_doc_ids` above — they were already removed, OR the
+    // sweep here removes them before we start counting).
+    //
+    // Critical design invariant: only purge when the file is TRULY
+    // absent from disk. A file that is still on disk but outside the
+    // current walker scope (config narrowing / include-glob change) is
+    // NOT purged — we leave it in place to protect against accidental
+    // data loss via config edits.
+    let scanned_paths: std::collections::HashSet<kebab_core::WorkspacePath> = assets
+        .iter()
+        .map(|a| a.workspace_path.clone())
+        .collect();
+    let purged_deleted_files = sweep_deleted_files(
+        &app,
+        &scanned_paths,
+        vector_store.as_ref().map(|v| v.as_ref()),
+    )?;
+
     let started_at = time::OffsetDateTime::now_utc();
 
     let mut items: Vec<kebab_core::IngestItem> = Vec::new();
@@ -635,11 +669,11 @@ pub fn ingest_with_config_opts(
     crate::ingest_progress::emit(progress, terminal_event);
 
     // p9-fb-19: bump the persistent corpus_revision counter when a
-    // commit landed (any new / updated). This invalidates every
+    // commit landed (any new / updated / purged). This invalidates every
     // entry in any in-process LRU search cache (in this process or
     // a sibling) on the next lookup. No-op when nothing changed
     // (skipped-only run) — the cache stays valid.
-    if new_count > 0 || updated_count > 0 {
+    if new_count > 0 || updated_count > 0 || purged_deleted_files > 0 {
         match app.sqlite.bump_corpus_revision() {
             Ok(rev) => tracing::debug!(
                 target: "kebab-app",
@@ -664,6 +698,13 @@ pub fn ingest_with_config_opts(
         errors: error_count,
         duration_ms,
         skipped_by_extension,
+        skipped_gitignore: fs_skips.skipped_gitignore,
+        skipped_kebabignore: fs_skips.skipped_kebabignore,
+        skipped_builtin_blacklist: fs_skips.skipped_builtin_blacklist,
+        skipped_generated: fs_skips.skipped_generated,
+        skipped_size_exceeded: fs_skips.skipped_size_exceeded,
+        skip_examples: fs_skips.skip_examples,
+        purged_deleted_files,
         items: if summary_only { None } else { Some(items) },
     })
 }
@@ -730,15 +771,18 @@ struct ImagePipeline<'a> {
 /// hold (per design §9 cascade rule):
 ///
 /// 1. `force_reingest == false` — caller hasn't asked to bypass skip.
-/// 2. The freshly-scanned asset's blake3 checksum equals what the
-///    existing `assets` row stores at the same `workspace_path`.
-/// 3. The doc keyed on `(workspace_path, asset_id, current_parser_version)`
-///    exists. If the parser_version changed, `id_for_doc` produces a
-///    different `doc_id` so the lookup misses → no skip → re-process.
-/// 4. The existing doc's stamped `last_chunker_version` AND
-///    `last_embedding_version` match the values the caller is about
-///    to use (`Some(v) == Some(v)` and `None == None` — see design
-///    doc for the `None == None` rule when no embedder is configured).
+/// 2. A document already exists at this `workspace_path`
+///    (`get_document_by_workspace_path`). The lookup is document-side, not
+///    asset-side, so twin files (identical content at different paths) each
+///    hit their own stable doc row — `documents.workspace_path` is UNIQUE
+///    while `assets` may dedupe content into a single row with a flip-flop
+///    `workspace_path` column (dogfood bug #4, see `tasks/HOTFIXES.md`).
+/// 3. The existing doc's `source_asset_id` equals the freshly-scanned
+///    asset's blake3 checksum (content unchanged).
+/// 4. The existing doc's `parser_version` matches the current extractor's
+///    `parser_version` (extractor not upgraded). Combined with `chunker_version`
+///    and `last_embedding_version` checks immediately below — full cascade
+///    per design §9.
 ///
 /// Returns `Ok(None)` (proceed with full re-process) when any check
 /// fails or any DB read errors out — the skip path is opportunistic;
@@ -755,31 +799,19 @@ fn try_skip_unchanged(
     if force_reingest {
         return Ok(None);
     }
-    let existing_asset = match app
+    // Document-centric skip: look up the existing document row by
+    // workspace_path directly. This avoids the twin-file flip-flop
+    // that the old asset-side lookup suffers from — multiple files
+    // with identical content share one `assets` row whose
+    // `workspace_path` is overwritten on every UPSERT, so
+    // `get_asset_by_workspace_path(path1)` could return the OTHER
+    // twin's path (or None) after any ingest of the twin. The
+    // `documents` table has a UNIQUE index on `workspace_path` (V001),
+    // so each twin has its own stable row regardless of asset de-dup.
+    let existing_doc = match app
         .sqlite
-        .get_asset_by_workspace_path(&asset.workspace_path)
+        .get_document_by_workspace_path(&asset.workspace_path)
     {
-        Ok(Some(a)) => a,
-        Ok(None) => return Ok(None),
-        Err(e) => {
-            tracing::debug!(
-                target: "kebab-app",
-                path = %asset.workspace_path.0,
-                error = %e,
-                "skip-check: get_asset_by_workspace_path failed; falling through to re-process"
-            );
-            return Ok(None);
-        }
-    };
-    if existing_asset.checksum != asset.checksum {
-        return Ok(None);
-    }
-    let candidate_doc_id = kebab_core::id_for_doc(
-        &asset.workspace_path,
-        &asset.asset_id,
-        current_parser_version,
-    );
-    let existing_doc = match app.sqlite.get_document(&candidate_doc_id) {
         Ok(Some(d)) => d,
         Ok(None) => return Ok(None),
         Err(e) => {
@@ -787,21 +819,37 @@ fn try_skip_unchanged(
                 target: "kebab-app",
                 path = %asset.workspace_path.0,
                 error = %e,
-                "skip-check: get_document failed; falling through to re-process"
+                "skip-check: get_document_by_workspace_path failed; falling through to re-process"
             );
             return Ok(None);
         }
     };
+    // 1. Content unchanged: the freshly-computed asset_id (blake3
+    //    content hash) must match what this document was ingested from.
+    if existing_doc.source_asset_id != asset.asset_id {
+        return Ok(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 {
+        return Ok(None);
+    }
+    // 3. Chunker unchanged.
     let chunker_match = existing_doc.last_chunker_version.as_ref()
         == Some(current_chunker_version);
     if !chunker_match {
         return Ok(None);
     }
+    // 4. Embedder unchanged.
     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,
@@ -900,7 +948,24 @@ fn ingest_one_asset(
                 force_reingest,
             );
         }
-        _ => {
+        // p10-1A-2 / 1B: code ingest dispatch.
+        MediaType::Code(lang)
+            if matches!(lang.as_str(), "rust" | "python" | "typescript" | "javascript") =>
+        {
+            return ingest_one_code_asset(
+                app,
+                asset,
+                chunk_policy,
+                embedder,
+                vector_store,
+                existing_doc_ids,
+                force_reingest,
+                lang.as_str(),
+            );
+        }
+        // p10-1A-2: non-Rust Code, Audio, and Other are not yet wired;
+        // skip until their respective phases.
+        MediaType::Code(_) | MediaType::Audio(_) | MediaType::Other(_) => {
             return Ok(kebab_core::IngestItem {
                 kind: kebab_core::IngestItemKind::Skipped,
                 doc_id: None,
@@ -1411,6 +1476,120 @@ fn purge_vector_orphans_for_workspace_path(
     Ok(())
 }
 
+/// Dogfood: post-walker sweep that purges stored documents whose source
+/// file has been physically deleted from the filesystem.
+///
+/// Algorithm:
+/// 1. Query `documents` for every `workspace_path` currently stored.
+/// 2. Compute `orphan_candidates = stored_paths - scanned_paths`.
+/// 3. For each candidate: resolve to an absolute path and call
+///    `Path::try_exists().unwrap_or(true)` — transient FS errors
+///    (EACCES, NFS hiccup, ownership change) conservatively count as
+///    "still present" so we never purge on uncertain signal. If the
+///    file still exists on disk it was merely out-of-scope this run
+///    (config narrowing / include-glob change) — leave it alone. Only
+///    files that are truly absent trigger a purge.
+/// 4. For absent files: call `purge_deleted_workspace_path` (SQLite
+///    cascade delete + optional copied-asset file removal) and, if a
+///    vector store is present, delete the associated vectors.
+///
+/// Returns the number of documents purged.
+///
+/// Non-fatal design: individual purge failures are logged and counted
+/// as errors on the per-file level but do NOT abort the sweep — a
+/// partial failure is preferable to blocking the rest of ingest. The
+/// return value only counts successful purges.
+fn sweep_deleted_files(
+    app: &App,
+    scanned_paths: &std::collections::HashSet<kebab_core::WorkspacePath>,
+    vector_store: Option<&kebab_store_vector::LanceVectorStore>,
+) -> anyhow::Result<u32> {
+    use kebab_core::DocumentStore as _;
+
+    let stored_paths = app
+        .sqlite
+        .all_workspace_paths()
+        .context("sweep_deleted_files: all_workspace_paths")?;
+
+    if stored_paths.is_empty() {
+        return Ok(0);
+    }
+
+    let workspace_root = app.config.resolve_workspace_root();
+    let mut purged: u32 = 0;
+
+    for stored_path in stored_paths {
+        if scanned_paths.contains(&stored_path) {
+            continue; // still in scope — skip
+        }
+
+        // Resolve to an absolute path and check existence on disk.
+        // Use `try_exists` + `unwrap_or(true)` so transient FS errors
+        // (EACCES on a path we lack read on, NFS hiccups, ownership
+        // change) are CONSERVATIVELY treated as "file still present" —
+        // never purge on uncertain signal (data-safety: PR #148 review).
+        // `exists()` would return false on Err and trigger a wrongful
+        // purge. Files whose path cannot be joined (theoretically
+        // impossible for non-empty workspace_path strings, but
+        // defense-in-depth) are likewise treated as still present.
+        let abs = workspace_root.join(&stored_path.0);
+        if abs.try_exists().unwrap_or(true) {
+            // File is on disk but not in this scan's scope (config
+            // narrowing). DO NOT purge — critical design constraint.
+            tracing::debug!(
+                target: "kebab-app",
+                path = %stored_path.0,
+                "sweep_deleted_files: file on disk but out of scope — leaving in store"
+            );
+            continue;
+        }
+
+        // File is truly absent → purge.
+        let chunk_ids = match kebab_store_sqlite::purge_deleted_workspace_path(
+            &app.sqlite,
+            &stored_path,
+        ) {
+            Ok(ids) => ids,
+            Err(e) => {
+                tracing::warn!(
+                    target: "kebab-app",
+                    path = %stored_path.0,
+                    error = %e,
+                    "sweep_deleted_files: purge failed; skipping this path"
+                );
+                continue;
+            }
+        };
+
+        // Purge associated vectors (best-effort; partial failure
+        // acceptable — orphan vectors get cleaned by `kebab reset
+        // --vector-only` if they accumulate).
+        if let Some(vec) = vector_store {
+            if !chunk_ids.is_empty() {
+                use kebab_core::VectorStore as _;
+                if let Err(e) = vec.delete_by_chunk_ids(&chunk_ids) {
+                    tracing::warn!(
+                        target: "kebab-app",
+                        path = %stored_path.0,
+                        count = chunk_ids.len(),
+                        error = %e,
+                        "sweep_deleted_files: vector delete failed; SQLite side already cleaned"
+                    );
+                }
+            }
+        }
+
+        tracing::info!(
+            target: "kebab-app",
+            path = %stored_path.0,
+            "sweep_deleted_files: purged document for deleted file"
+        );
+        purged = purged.saturating_add(1);
+    }
+
+    Ok(purged)
+}
+
 /// P7-3: process one `MediaType::Pdf` asset end-to-end.
 ///
 /// - Reads bytes from disk.
@@ -1600,6 +1779,213 @@ fn ingest_one_pdf_asset(
     })
 }
 
+/// p10-1A-2 Task 8: process one `MediaType::Code("rust")` asset end-to-end.
+///
+/// Mirrors `ingest_one_pdf_asset` line-for-line with the substitutions
+/// documented in the task spec:
+///   - parser_version → `code-rust-v1` (via `RUST_PARSER_VERSION`)
+///   - extractor     → `RustAstExtractor`
+///   - chunker       → `CodeRustAstV1Chunker`
+///
+/// All other steps (incremental skip, byte read, ExtractContext, put_*,
+/// embed, purge_vector_orphans) are identical to the PDF function.
+#[allow(clippy::too_many_arguments)]
+fn ingest_one_code_asset(
+    app: &App,
+    asset: &RawAsset,
+    chunk_policy: &ChunkPolicy,
+    embedder: Option<&Arc<dyn Embedder + Send + Sync>>,
+    vector_store: Option<&Arc<kebab_store_vector::LanceVectorStore>>,
+    existing_doc_ids: &std::collections::HashSet<String>,
+    force_reingest: bool,
+    code_lang: &str,                        // <-- NEW (p10-1b Task D)
+) -> anyhow::Result<kebab_core::IngestItem> {
+    let path = match &asset.source_uri {
+        SourceUri::File(p) => p.clone(),
+        SourceUri::Kb(_) => {
+            return Ok(kebab_core::IngestItem {
+                kind: kebab_core::IngestItemKind::Skipped,
+                doc_id: None,
+                doc_path: asset.workspace_path.clone(),
+                asset_id: Some(asset.asset_id.clone()),
+                byte_len: Some(asset.byte_len),
+                block_count: None,
+                chunk_count: None,
+                parser_version: None,
+                chunker_version: None,
+                warnings: vec![
+                    "kb:// URI not yet supported".to_string(),
+                ],
+                error: None,
+            });
+        }
+    };
+
+    // p10-1b Task D/G/J: parser_version per-lang.
+    let parser_version = match code_lang {
+        "rust"       => ParserVersion(kebab_parse_code::RUST_PARSER_VERSION.to_string()),
+        "python"     => ParserVersion(kebab_parse_code::PYTHON_PARSER_VERSION.to_string()),
+        "typescript" => ParserVersion(kebab_parse_code::TS_PARSER_VERSION.to_string()),
+        "javascript" => ParserVersion(kebab_parse_code::JS_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 {
+        "rust"       => CodeRustAstV1Chunker.chunker_version(),
+        "python"     => CodePythonAstV1Chunker.chunker_version(),
+        "typescript" => CodeTsAstV1Chunker.chunker_version(),
+        "javascript" => CodeJsAstV1Chunker.chunker_version(),
+        other => anyhow::bail!("unreachable chunker_version: {other}"),
+    };
+
+    if let Some(item) = try_skip_unchanged(
+        app,
+        asset,
+        &parser_version,
+        &chunker_version,
+        embedder.map(|e| e.model_version()).as_ref(),
+        force_reingest,
+    )? {
+        return Ok(item);
+    }
+    let bytes = std::fs::read(&path)
+        .with_context(|| format!("read code asset bytes from {}", path.display()))?;
+
+    let extract_config = kebab_core::ExtractConfig::default();
+    let workspace_root = app.config.resolve_workspace_root();
+    let ctx = ExtractContext {
+        asset,
+        workspace_root: &workspace_root,
+        config: &extract_config,
+    };
+
+    // p10-1b Task D/G/J/L: extractor per-lang.
+    let mut canonical = match code_lang {
+        "rust" => RustAstExtractor::new()
+            .extract(&ctx, &bytes)
+            .context("kb-parse-code::RustAstExtractor::extract (code:rust)")?,
+        "python" => PythonAstExtractor::new()
+            .extract(&ctx, &bytes)
+            .context("kb-parse-code::PythonAstExtractor::extract (code:python)")?,
+        "typescript" => TypescriptAstExtractor::new()
+            .extract(&ctx, &bytes)
+            .context("kb-parse-code::TypescriptAstExtractor::extract (code:typescript)")?,
+        "javascript" => JavascriptAstExtractor::new()
+            .extract(&ctx, &bytes)
+            .context("kb-parse-code::JavascriptAstExtractor::extract (code:javascript)")?,
+        other => anyhow::bail!("unreachable (extract): {other}"),
+    };
+
+    // p10-1b Task D/G/J/L: chunker per-lang.
+    let chunks = 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)")?,
+        other => anyhow::bail!("unreachable (chunk): {other}"),
+    };
+
+    // Stamp chunker + embedding versions so incremental skip detection has
+    // data on the second run.
+    canonical.last_chunker_version = Some(chunker_version.clone());
+    if let Some(emb) = embedder {
+        canonical.last_embedding_version = Some(emb.model_version());
+    }
+
+    purge_vector_orphans_for_workspace_path(app, asset, vector_store)?;
+    app.sqlite
+        .put_asset_with_bytes(asset, &bytes)
+        .context("DocumentStore::put_asset_with_bytes (code)")?;
+    app.sqlite
+        .put_document(&canonical)
+        .context("DocumentStore::put_document (code)")?;
+    app.sqlite
+        .put_blocks(&canonical.doc_id, &canonical.blocks)
+        .context("DocumentStore::put_blocks (code)")?;
+    app.sqlite
+        .put_chunks(&canonical.doc_id, &chunks)
+        .context("DocumentStore::put_chunks (code)")?;
+
+    if let (Some(emb), Some(vec_store)) = (embedder, vector_store)
+        && !chunks.is_empty()
+    {
+        let inputs: Vec<EmbeddingInput<'_>> = chunks
+            .iter()
+            .map(|c| EmbeddingInput {
+                text: c.text.as_str(),
+                kind: EmbeddingKind::Document,
+            })
+            .collect();
+        let vectors = emb
+            .embed(&inputs)
+            .context("Embedder::embed (code chunks)")?;
+        let model_id = emb.model_id();
+        let model_version = emb.model_version();
+        let dimensions = emb.dimensions();
+        let records: Vec<VectorRecord> = chunks
+            .iter()
+            .zip(vectors)
+            .map(|(c, v)| VectorRecord {
+                embedding_id: kebab_core::id_for_embedding(
+                    &c.chunk_id,
+                    &model_id,
+                    &model_version,
+                    dimensions,
+                ),
+                chunk_id: c.chunk_id.clone(),
+                vector: v,
+                doc_id: canonical.doc_id.clone(),
+                text: c.text.clone(),
+                heading_path: c.heading_path.clone(),
+                model_id: model_id.clone(),
+                model_version: model_version.clone(),
+                dimensions,
+            })
+            .collect();
+        vec_store
+            .upsert(&records)
+            .context("VectorStore::upsert (code)")?;
+    }
+
+    let kind = if existing_doc_ids.contains(&canonical.doc_id.0) {
+        kebab_core::IngestItemKind::Updated
+    } else {
+        kebab_core::IngestItemKind::New
+    };
+
+    // Surface every `Provenance::Warning` note onto `IngestItem.warnings`.
+    let warnings: Vec<String> = canonical
+        .provenance
+        .events
+        .iter()
+        .filter(|e| e.kind == kebab_core::ProvenanceKind::Warning)
+        .filter_map(|e| e.note.clone())
+        .collect();
+
+    Ok(kebab_core::IngestItem {
+        kind,
+        doc_id: Some(canonical.doc_id.clone()),
+        doc_path: asset.workspace_path.clone(),
+        asset_id: Some(asset.asset_id.clone()),
+        byte_len: Some(asset.byte_len),
+        block_count: u32::try_from(canonical.blocks.len()).ok(),
+        chunk_count: u32::try_from(chunks.len()).ok(),
+        parser_version: Some(canonical.parser_version.clone()),
+        chunker_version: Some(chunker_version),
+        warnings,
+        error: None,
+    })
+}
+
 /// Pull the BCP-47 language hint from the canonical document. P6-1
 /// stamps `Lang("und")` by default; image-pipeline OCR / caption
 /// adapters special-case "und" so the hint is intentionally dropped
@@ -1734,6 +2120,19 @@ pub fn search_uncached_with_config(
     App::open_with_config(config)?.search_uncached(query)
 }
 
+/// p9-fb-34: budget-aware search free function. Mirrors
+/// [`search_with_config`] but threads `SearchOpts` (max_tokens,
+/// snippet_chars, cursor) and returns the [`SearchResponse`]
+/// pagination wrapper. Tasks 6+8 surface this via CLI / MCP.
+#[doc(hidden)]
+pub fn search_with_opts_with_config(
+    config: kebab_config::Config,
+    query: kebab_core::SearchQuery,
+    opts: kebab_core::SearchOpts,
+) -> anyhow::Result<SearchResponse> {
+    App::open_with_config(config)?.search_with_opts(query, opts)
+}
+
 // ── ask ──────────────────────────────────────────────────────────────────
 //
 // P4-3 wires `ask` end-to-end. The retriever is built per `opts.mode`;
@@ -1872,3 +2271,143 @@ pub fn doctor_with_config_path(config_path: Option<&std::path::Path>) -> anyhow:
 pub fn doctor() -> anyhow::Result<DoctorReport> {
     doctor_with_config_path(None)
 }
+
+/// Single-file ingest (p9-fb-31). Copies the file to
+/// `<workspace.root>/_external/<blake3-12>.<ext>` and runs the
+/// per-medium ingest pipeline on that single asset. Returns an
+/// `IngestReport` with `scanned: 1` (and either `new: 1` or
+/// `unchanged: 1` depending on whether the content hash + version
+/// cascade match an existing doc — incremental ingest from p9-fb-23).
+///
+/// `path` may point inside or outside the workspace.
+///
+/// `.kebabignore` patterns matching `path` are bypassed with a stderr
+/// `warn:` line — explicit ingest is intent.
+#[doc(hidden)]
+pub fn ingest_file_with_config(
+    config: kebab_config::Config,
+    path: &std::path::Path,
+) -> anyhow::Result<IngestReport> {
+    if !path.exists() {
+        anyhow::bail!("ingest-file: source path does not exist: {}", path.display());
+    }
+    if !path.is_file() {
+        anyhow::bail!("ingest-file: not a regular file: {}", path.display());
+    }
+
+    let ext_raw = path
+        .extension()
+        .and_then(|e| e.to_str())
+        .ok_or_else(|| anyhow::anyhow!("ingest-file: source has no extension: {}", path.display()))?;
+    let ext = ext_raw.to_lowercase();
+
+    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
+        );
+    }
+
+    let bytes = std::fs::read(path)
+        .with_context(|| format!("ingest-file: read source {}", path.display()))?;
+
+    let workspace_root = config.resolve_workspace_root();
+
+    // .kebabignore check — warn but continue.
+    let ignore_match = check_kebabignore_match(&workspace_root, path);
+    if ignore_match {
+        eprintln!(
+            "warn: {} matches .kebabignore patterns; proceeding (explicit ingest bypasses ignore)",
+            path.display()
+        );
+    }
+
+    // Set up _external/ dir + auto-ignore line.
+    let external_dir = crate::external::ensure_external_dir(&workspace_root)
+        .context("ingest-file: ensure _external/ dir")?;
+    crate::external::ensure_kebabignore_entry(&workspace_root)
+        .context("ingest-file: append _external/ to .kebabignore")?;
+
+    // Copy bytes to _external/<hash>.<ext>.
+    let dest = crate::external::copy_to_external(&external_dir, &bytes, &ext)
+        .context("ingest-file: copy to _external")?;
+
+    // Build a SourceScope that targets _external/ with include filter
+    // restricting walk to the single dest filename.
+    let filename = dest
+        .file_name()
+        .ok_or_else(|| anyhow::anyhow!("ingest-file: dest has no filename"))?
+        .to_string_lossy()
+        .into_owned();
+    let scope = kebab_core::SourceScope {
+        root: external_dir.clone(),
+        include: vec![filename],
+        exclude: config.workspace.exclude.clone(),
+    };
+
+    let opts = IngestOpts::default();
+    ingest_with_config_opts(config, scope, /* summary_only = */ false, opts)
+}
+
+/// Stdin ingest (p9-fb-31, v1 markdown only). Prepends a YAML
+/// frontmatter block (`title` + optional `source_uri`) to `body`,
+/// writes the wrapped markdown to `_external/<hash12>.md`, and runs
+/// `ingest_file_with_config` on the resulting file.
+///
+/// Errors if `body` already starts with `---` (the user should call
+/// `ingest_file_with_config` directly for files that already carry
+/// frontmatter).
+#[doc(hidden)]
+pub fn ingest_stdin_with_config(
+    config: kebab_config::Config,
+    body: &str,
+    title: &str,
+    source_uri: Option<&str>,
+) -> anyhow::Result<IngestReport> {
+    let wrapped = crate::external::inject_frontmatter(body, title, source_uri)?;
+
+    let workspace_root = config.resolve_workspace_root();
+    // Note: ensure_external_dir + ensure_kebabignore_entry + copy_to_external
+    // are called here AND inside ingest_file_with_config. All three are
+    // idempotent; the redundancy is intentional — keeping stdin's wrapped
+    // bytes accessible by `ingest_file_with_config` requires the dest path
+    // to exist. The ~ms double-stat overhead is negligible at v1 scale.
+    let external_dir = crate::external::ensure_external_dir(&workspace_root)?;
+    crate::external::ensure_kebabignore_entry(&workspace_root)?;
+
+    let dest = crate::external::copy_to_external(
+        &external_dir,
+        wrapped.as_bytes(),
+        "md",
+    )?;
+
+    ingest_file_with_config(config, &dest)
+}
+
+/// Returns true if `source_path` matches any `.kebabignore` pattern
+/// rooted at `workspace_root`. Used by `ingest_file_with_config` to
+/// emit a stderr warn before bypassing the ignore.
+fn check_kebabignore_match(workspace_root: &std::path::Path, source_path: &std::path::Path) -> bool {
+    let kebabignore = workspace_root.join(".kebabignore");
+    if !kebabignore.exists() {
+        return false;
+    }
+    let text = match std::fs::read_to_string(&kebabignore) {
+        Ok(s) => s,
+        Err(_) => return false,
+    };
+    let mut builder = ignore::gitignore::GitignoreBuilder::new(workspace_root);
+    for line in text.lines() {
+        let line = line.trim();
+        if line.is_empty() || line.starts_with('#') {
+            continue;
+        }
+        let _ = builder.add_line(None, line);
+    }
+    let matcher = match builder.build() {
+        Ok(m) => m,
+        Err(_) => return false,
+    };
+    matcher.matched(source_path, source_path.is_dir()).is_ignore()
+}

crates/kebab-app/src/reset.rs

@@ -9,13 +9,19 @@
 //!
 //! `--vector-only` additionally truncates `embedding_records` in SQLite
 //! so the next `kebab ingest` re-embeds cleanly without orphan rows.
+//!
+//! `--orphans-only` purges stored docs that are outside the current walker
+//! scope (config narrowing / removed sub-directory). No filesystem paths are
+//! removed — this is purely a store-level reconciliation.
 
+use std::collections::HashSet;
 use std::path::PathBuf;
 
 use anyhow::{Context, Result};
 use serde::{Deserialize, Serialize};
 
 use kebab_config::{Config, expand_path};
+use kebab_core::WorkspacePath;
 
 /// What the user asked to remove. Mutually exclusive — picked by the CLI
 /// from a clap `ArgGroup`.
@@ -32,6 +38,13 @@ pub enum ResetScope {
     VectorOnly,
     /// Wipe only the config dir.
     ConfigOnly,
+    /// Purge stored docs that are outside the current walker scope (no
+    /// filesystem paths are removed). Filesystem existence is NOT checked —
+    /// anything the current walker would not visit is considered an orphan.
+    /// The explicit complement to the conservative `sweep_deleted_files`
+    /// that runs during ingest (which leaves on-disk-but-out-of-scope docs
+    /// alone for data safety).
+    OrphansOnly,
 }
 
 /// Result of a successful wipe — emitted as `reset_report.v1` by the
@@ -41,6 +54,16 @@ pub struct ResetReport {
     pub scope: ResetScope,
     pub removed_paths: Vec<PathBuf>,
     pub embedding_rows_truncated: u64,
+    /// Number of stored docs purged because they are outside the current
+    /// walker scope. Non-zero only when `scope == OrphansOnly`.
+    /// `#[serde(default)]` preserves back-compat with older callers that
+    /// do not include this field.
+    #[serde(default)]
+    pub orphans_purged: u32,
+    /// Paths of the orphaned docs that were purged. Sorted for deterministic
+    /// output. Non-empty only when `scope == OrphansOnly`.
+    #[serde(default)]
+    pub purged_paths: Vec<WorkspacePath>,
 }
 
 /// Compute the absolute on-disk paths a given scope will wipe, given a
@@ -67,6 +90,10 @@ pub fn enumerate_paths(scope: ResetScope, cfg: &Config) -> Vec<PathBuf> {
             vec![vector_dir]
         }
         ResetScope::ConfigOnly => vec![cfg_dir],
+        // OrphansOnly operates purely at the store level — no filesystem paths
+        // are removed. Return empty so `estimate_size_bytes` stays zero and
+        // the existing confirm UI path for directory wipes is skipped.
+        ResetScope::OrphansOnly => vec![],
     }
 }
 
@@ -96,16 +123,82 @@ pub fn estimate_size_bytes(paths: &[PathBuf]) -> u64 {
     paths.iter().map(|p| walk(p)).sum()
 }
 
+/// Compute the workspace paths stored in SQLite that are NOT visited by
+/// the current walker scope (i.e. they are "orphans" — on disk but
+/// outside the configured include/exclude rules, or from a sub-directory
+/// that has since been removed from the workspace).
+///
+/// Does NOT check filesystem existence — `OrphansOnly` is the explicit
+/// "I know what I'm doing" variant; callers that want the conservative
+/// fs-aware sweep should use `sweep_deleted_files` inside ingest.
+///
+/// Returns the list sorted for deterministic output. Called twice by the
+/// CLI path (once for the confirm UI preview, once inside `execute`);
+/// the double scan is acceptable for a rare destructive operation.
+pub fn enumerate_orphans(cfg: &Config) -> Result<Vec<WorkspacePath>> {
+    use kebab_core::DocumentStore as _;
+    use kebab_source_fs::FsSourceConnector;
+    use kebab_core::SourceScope;
+
+    let store = kebab_store_sqlite::SqliteStore::open(cfg)
+        .context("enumerate_orphans: open SqliteStore")?;
+
+    let stored = store
+        .all_workspace_paths()
+        .context("enumerate_orphans: all_workspace_paths")?;
+
+    if stored.is_empty() {
+        return Ok(Vec::new());
+    }
+
+    // Build the same SourceScope the CLI's ingest path uses: root from
+    // config, exclude list from config, no include override (full scope).
+    let root = cfg.resolve_workspace_root();
+    let scope = SourceScope {
+        root: root.clone(),
+        exclude: cfg.workspace.exclude.clone(),
+        ..Default::default()
+    };
+
+    let connector = FsSourceConnector::new(cfg)
+        .context("enumerate_orphans: build FsSourceConnector")?;
+    let (assets, _skips) = connector
+        .scan_with_skips(&scope)
+        .context("enumerate_orphans: scan workspace")?;
+
+    let scanned: HashSet<WorkspacePath> = assets
+        .into_iter()
+        .map(|a| a.workspace_path)
+        .collect();
+
+    let mut orphans: Vec<WorkspacePath> = stored
+        .into_iter()
+        .filter(|p| !scanned.contains(p))
+        .collect();
+    orphans.sort_by(|a, b| a.0.cmp(&b.0));
+    Ok(orphans)
+}
+
 /// Wipe every path from `enumerate_paths(scope, cfg)`. For
 /// `ResetScope::VectorOnly`, also truncates the SQLite
 /// `embedding_records` table so the store doesn't point at the Lance
 /// rows we just removed off-disk.
 ///
+/// For `ResetScope::OrphansOnly`, no filesystem directories are removed.
+/// Instead the store is reconciled: stored docs outside the current walker
+/// scope are purged from SQLite (+ vector store when configured). The
+/// caller is expected to have already shown the confirm UI using
+/// `enumerate_orphans`.
+///
 /// Idempotent: a missing path is treated as already-removed (success).
 /// Returns a `ResetReport` listing exactly what was removed (paths that
 /// existed before the call) so `--json` callers see the truth, not the
 /// request.
 pub fn execute(scope: ResetScope, cfg: &Config) -> Result<ResetReport> {
+    if matches!(scope, ResetScope::OrphansOnly) {
+        return execute_orphans_only(cfg);
+    }
+
     let paths = enumerate_paths(scope, cfg);
     let mut removed = Vec::new();
 
@@ -128,9 +221,100 @@ pub fn execute(scope: ResetScope, cfg: &Config) -> Result<ResetReport> {
         scope,
         removed_paths: removed,
         embedding_rows_truncated,
+        orphans_purged: 0,
+        purged_paths: Vec::new(),
     })
 }
 
+/// Execute the `OrphansOnly` variant: reconcile stored docs against the
+/// current walker scope without touching any filesystem directory.
+fn execute_orphans_only(cfg: &Config) -> Result<ResetReport> {
+    let orphans = enumerate_orphans(cfg)
+        .context("execute_orphans_only: enumerate orphans")?;
+
+    if orphans.is_empty() {
+        return Ok(ResetReport {
+            scope: ResetScope::OrphansOnly,
+            removed_paths: Vec::new(),
+            embedding_rows_truncated: 0,
+            orphans_purged: 0,
+            purged_paths: Vec::new(),
+        });
+    }
+
+    let store = std::sync::Arc::new(
+        kebab_store_sqlite::SqliteStore::open(cfg)
+            .context("execute_orphans_only: open SqliteStore")?,
+    );
+
+    // Open vector store if configured. Mirror the same guard the ingest
+    // path uses: only construct when the provider is not "none" / dims > 0.
+    let vector_store: Option<kebab_store_vector::LanceVectorStore> =
+        open_vector_store_if_configured(cfg, store.clone())?;
+
+    let mut purged_paths: Vec<WorkspacePath> = Vec::new();
+
+    for path in &orphans {
+        let chunk_ids = kebab_store_sqlite::purge_deleted_workspace_path(&store, path)
+            .with_context(|| format!("execute_orphans_only: purge {}", path.0))?;
+
+        if let Some(ref vs) = vector_store {
+            if !chunk_ids.is_empty() {
+                use kebab_core::VectorStore as _;
+                if let Err(e) = vs.delete_by_chunk_ids(&chunk_ids) {
+                    tracing::warn!(
+                        target: "kebab-app",
+                        path = %path.0,
+                        count = chunk_ids.len(),
+                        error = %e,
+                        "reset --orphans-only: vector delete failed; SQLite side already cleaned"
+                    );
+                }
+            }
+        }
+
+        tracing::info!(
+            target: "kebab-app",
+            path = %path.0,
+            "reset --orphans-only: purged orphan document"
+        );
+        purged_paths.push(path.clone());
+    }
+
+    let orphans_purged = u32::try_from(purged_paths.len()).unwrap_or(u32::MAX);
+
+    Ok(ResetReport {
+        scope: ResetScope::OrphansOnly,
+        removed_paths: Vec::new(),
+        embedding_rows_truncated: 0,
+        orphans_purged,
+        purged_paths,
+    })
+}
+
+/// Open the Lance vector store if the configured embedding provider is
+/// active (non-"none", dimensions > 0). Returns `None` for lexical-only
+/// configs. Mirrors the guard in `App::vector`.
+fn open_vector_store_if_configured(
+    cfg: &Config,
+    store: std::sync::Arc<kebab_store_sqlite::SqliteStore>,
+) -> Result<Option<kebab_store_vector::LanceVectorStore>> {
+    if cfg.models.embedding.provider == "none" || cfg.models.embedding.dimensions == 0 {
+        return Ok(None);
+    }
+    match kebab_store_vector::LanceVectorStore::new(cfg, store) {
+        Ok(vs) => Ok(Some(vs)),
+        Err(e) => {
+            tracing::warn!(
+                target: "kebab-app",
+                error = %e,
+                "reset --orphans-only: could not open vector store; skipping vector delete"
+            );
+            Ok(None)
+        }
+    }
+}
+
 /// Open the SQLite store at the configured path and run
 /// `truncate_embedding_records`. Returns the count of truncated rows
 /// (the helper itself reports `DELETE` rowcount). If the SQLite file
@@ -200,4 +384,14 @@ mod tests {
         let bytes = estimate_size_bytes(&[dir.path().to_path_buf()]);
         assert_eq!(bytes, 5 + 6);
     }
+
+    #[test]
+    fn enumerate_orphans_only_returns_empty_paths() {
+        let cfg = Config::defaults();
+        let paths = enumerate_paths(ResetScope::OrphansOnly, &cfg);
+        assert!(
+            paths.is_empty(),
+            "OrphansOnly must return empty vec from enumerate_paths"
+        );
+    }
 }

crates/kebab-app/src/schema.rs

@@ -32,6 +32,7 @@ pub struct Capabilities {
     pub http_daemon: bool,
     pub mcp_server: bool,
     pub single_file_ingest: bool,
+    pub bulk_search: bool,
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
@@ -44,12 +45,32 @@ pub struct Models {
     pub corpus_revision: u64,
 }
 
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
 pub struct Stats {
     pub doc_count: u64,
     pub chunk_count: u64,
     pub asset_count: u64,
     pub last_ingest_at: Option<String>,
+    /// p9-fb-37: per-media-kind doc count (5 keys, zero-padded).
+    #[serde(default)]
+    pub media_breakdown: std::collections::BTreeMap<String, u64>,
+    /// p9-fb-37: per-language doc count, NULL keyed as `"null"`.
+    #[serde(default)]
+    pub lang_breakdown: std::collections::BTreeMap<String, u64>,
+    /// p9-fb-37: on-disk byte sums.
+    #[serde(default)]
+    pub index_bytes: kebab_core::IndexBytes,
+    /// 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.
+    #[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.
+    #[serde(default)]
+    pub repo_breakdown: std::collections::BTreeMap<String, u32>,
 }
 
 const KEBAB_VERSION: &str = env!("CARGO_PKG_VERSION");
@@ -63,6 +84,7 @@ pub const SCHEMA_V1_ID: &str = "schema.v1";
 const WIRE_SCHEMAS: &[&str] = &[
     "answer.v1",
     "search_hit.v1",
+    "search_response.v1",
     "doc_summary.v1",
     "chunk_inspection.v1",
     "doctor.v1",
@@ -72,6 +94,8 @@ const WIRE_SCHEMAS: &[&str] = &[
     "citation.v1",
     "schema.v1",
     "error.v1",
+    "bulk_search_item.v1",
+    "bulk_search_response.v1",
 ];
 
 /// Build a [`SchemaV1`] introspection report for the given config.
@@ -84,7 +108,7 @@ const WIRE_SCHEMAS: &[&str] = &[
 #[doc(hidden)]
 pub fn schema_with_config(cfg: &Config) -> anyhow::Result<SchemaV1> {
     let store = open_store_for_stats(cfg)?;
-    let stats = collect_stats(&store)?;
+    let stats = collect_stats(cfg, &store)?;
     let models = collect_models(cfg, &store);
     Ok(SchemaV1 {
         schema_version: SCHEMA_V1_ID.to_string(),
@@ -108,8 +132,9 @@ fn capabilities_snapshot() -> Capabilities {
         incremental_ingest: true,
         streaming_ask: false,
         http_daemon: false,
-        mcp_server: false,
+        mcp_server: true,
         single_file_ingest: false,
+        bulk_search: true,
     }
 }
 
@@ -123,13 +148,29 @@ fn open_store_for_stats(cfg: &Config) -> anyhow::Result<kebab_store_sqlite::Sqli
     kebab_store_sqlite::SqliteStore::open_existing(&db_path)
 }
 
-fn collect_stats(store: &kebab_store_sqlite::SqliteStore) -> anyhow::Result<Stats> {
-    let counts = store.count_summary()?;
+fn collect_stats(
+    cfg: &Config,
+    store: &kebab_store_sqlite::SqliteStore,
+) -> anyhow::Result<Stats> {
+    let counts = store
+        .count_summary_with_threshold(cfg.search.stale_threshold_days as u64)?;
+    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}"))?;
     Ok(Stats {
         doc_count: counts.doc_count,
         chunk_count: counts.chunk_count,
         asset_count: counts.asset_count,
         last_ingest_at: counts.last_ingest_at,
+        media_breakdown: counts.media_breakdown,
+        lang_breakdown: counts.lang_breakdown,
+        index_bytes,
+        stale_doc_count: counts.stale_doc_count,
+        // p10-1A-2: populated by the store query added in this task.
+        code_lang_breakdown: store.code_lang_breakdown()?,
+        // 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()?,
     })
 }
 
@@ -149,3 +190,57 @@ fn collect_models(cfg: &Config, store: &kebab_store_sqlite::SqliteStore) -> Mode
         corpus_revision: store.corpus_revision(),
     }
 }
+
+#[cfg(test)]
+mod tests_stats_ext {
+    use super::*;
+
+    /// p10-1A-1: Stats must serialize `code_lang_breakdown` and
+    /// `repo_breakdown` so downstream consumers (MCP skill, Claude Code)
+    /// can branch on their presence.
+    #[test]
+    fn stats_includes_code_lang_and_repo_breakdown_fields() {
+        let stats = Stats::default();
+        let v = serde_json::to_value(&stats).unwrap();
+        assert!(
+            v.get("code_lang_breakdown").is_some(),
+            "Stats JSON must include code_lang_breakdown: {v}"
+        );
+        assert!(
+            v.get("repo_breakdown").is_some(),
+            "Stats JSON must include repo_breakdown: {v}"
+        );
+        // Empty BTreeMap serializes as `{}` — confirm it's an object, not null.
+        assert!(
+            v["code_lang_breakdown"].is_object(),
+            "code_lang_breakdown must be an object: {v}"
+        );
+        assert!(
+            v["repo_breakdown"].is_object(),
+            "repo_breakdown must be an object: {v}"
+        );
+    }
+
+    #[test]
+    fn stats_includes_breakdowns_and_bytes_on_fresh_corpus() {
+        let dir = tempfile::tempdir().unwrap();
+        let mut cfg = kebab_config::Config::defaults();
+        cfg.storage.data_dir = dir.path().to_string_lossy().into_owned();
+        // Bring up migrations so the sqlite file is created.
+        let store = kebab_store_sqlite::SqliteStore::open(&cfg).unwrap();
+        store.run_migrations().unwrap();
+        drop(store);
+
+        let s = schema_with_config(&cfg).unwrap();
+        // 5 keys padded.
+        assert_eq!(s.stats.media_breakdown.len(), 5);
+        assert_eq!(s.stats.media_breakdown.get("markdown"), Some(&0));
+        assert_eq!(s.stats.media_breakdown.get("pdf"), Some(&0));
+        // lang map empty on empty corpus.
+        assert!(s.stats.lang_breakdown.is_empty());
+        // sqlite bytes positive after migrations, lancedb 0.
+        assert!(s.stats.index_bytes.sqlite > 0);
+        assert_eq!(s.stats.index_bytes.lancedb, 0);
+        assert_eq!(s.stats.stale_doc_count, 0);
+    }
+}

crates/kebab-app/src/staleness.rs

@@ -0,0 +1,77 @@
+//! p9-fb-32 staleness helpers.
+
+use time::{Duration, OffsetDateTime};
+
+use kebab_core::SearchHit;
+
+/// Returns `true` iff `now - indexed_at > threshold_days * 24h`.
+/// `threshold_days = 0` always returns `false` (feature disabled).
+/// Strict `>` so that exactly `threshold_days` old returns `false`.
+///
+/// p9-fb-32: mirrored in `kebab_rag::pipeline::compute_stale` (dep-boundary
+/// rule prevents `kebab-rag → kebab-app`). Update both together.
+pub fn compute_stale(
+    indexed_at: OffsetDateTime,
+    now: OffsetDateTime,
+    threshold_days: u32,
+) -> bool {
+    if threshold_days == 0 {
+        return false;
+    }
+    let threshold = Duration::days(i64::from(threshold_days));
+    (now - indexed_at) > threshold
+}
+
+/// Sets `stale` on each hit in place using `compute_stale`.
+pub fn mark_stale_in_place(
+    hits: &mut [SearchHit],
+    now: OffsetDateTime,
+    threshold_days: u32,
+) {
+    for h in hits {
+        h.stale = compute_stale(h.indexed_at, now, threshold_days);
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use time::macros::datetime;
+
+    fn now() -> OffsetDateTime {
+        datetime!(2026-05-09 12:00:00 UTC)
+    }
+
+    #[test]
+    fn threshold_zero_always_fresh() {
+        let very_old = datetime!(2020-01-01 00:00:00 UTC);
+        assert!(!compute_stale(very_old, now(), 0));
+    }
+
+    #[test]
+    fn just_under_threshold_is_fresh() {
+        // 29 days, 23h, 59m old — under 30d.
+        let indexed = now() - Duration::days(29) - Duration::hours(23) - Duration::minutes(59);
+        assert!(!compute_stale(indexed, now(), 30));
+    }
+
+    #[test]
+    fn exactly_threshold_is_fresh() {
+        // strict `>` boundary: exactly 30d old is still fresh.
+        let indexed = now() - Duration::days(30);
+        assert!(!compute_stale(indexed, now(), 30));
+    }
+
+    #[test]
+    fn one_minute_past_threshold_is_stale() {
+        let indexed = now() - Duration::days(30) - Duration::minutes(1);
+        assert!(compute_stale(indexed, now(), 30));
+    }
+
+    #[test]
+    fn future_indexed_at_is_fresh() {
+        // clock skew safety: future timestamps must not be stale.
+        let future = now() + Duration::hours(1);
+        assert!(!compute_stale(future, now(), 30));
+    }
+}

crates/kebab-app/tests/code_ingest_smoke.rs

@@ -0,0 +1,431 @@
+//! p10-1A-2 Task 8: smoke test for Rust code ingest dispatch.
+//!
+//! Writes a single `.rs` file into a TempDir workspace, ingests it via
+//! `kebab_app::ingest_with_config`, then searches for the symbol name and
+//! asserts that the resulting `SearchHit` carries a `Citation::Code`
+//! with the expected `lang`, `symbol`, and `line_start`.
+//!
+//! Mirrors the `pdf_pipeline.rs` harness: lexical-only (no AVX/fastembed),
+//! no OCR / caption adapters needed.
+
+mod common;
+
+use common::{TestEnv, lexical_query};
+
+use kebab_core::{Citation, IngestItemKind};
+
+/// A `.rs` file with a single `pub fn add` symbol is ingested, and a
+/// lexical search for "add" must return at least one `Citation::Code`
+/// hit whose `lang == "rust"`, `symbol == Some("add")`, and
+/// `line_start >= 1`.
+#[test]
+fn rust_file_ingests_and_searches_as_code_citation() {
+    let env = TestEnv::lexical_only();
+
+    // Write a minimal Rust file into the workspace root.
+    std::fs::write(
+        env.workspace_root.join("demo.rs"),
+        "/// adds two integers\npub fn add(a: i32, b: i32) -> i32 {\n    a + b\n}\n",
+    )
+    .unwrap();
+
+    let report =
+        kebab_app::ingest_with_config(env.config.clone(), env.scope(), false)
+            .expect("ingest must succeed");
+
+    assert_eq!(report.errors, 0, "no errors expected: {report:?}");
+    let items = report.items.as_ref().expect("items present");
+    let code_item = items
+        .iter()
+        .find(|i| i.doc_path.0.ends_with("demo.rs"))
+        .expect("demo.rs item present");
+    assert_eq!(
+        code_item.kind,
+        IngestItemKind::New,
+        "first ingest must be New: {code_item:?}"
+    );
+    assert!(
+        code_item.block_count.unwrap_or(0) >= 1,
+        "at least one block expected: {code_item:?}"
+    );
+    assert!(
+        code_item.chunk_count.unwrap_or(0) >= 1,
+        "at least one chunk expected: {code_item:?}"
+    );
+    assert_eq!(
+        code_item.parser_version.as_ref().map(|p| p.0.as_str()),
+        Some("code-rust-v1"),
+        "parser_version must be code-rust-v1"
+    );
+    assert_eq!(
+        code_item.chunker_version.as_ref().map(|c| c.0.as_str()),
+        Some("code-rust-ast-v1"),
+        "chunker_version must be code-rust-ast-v1"
+    );
+
+    // Lexical search for the symbol name "add".
+    let hits = kebab_app::search_with_config(env.config.clone(), lexical_query("add"))
+        .expect("search must succeed");
+
+    let h = hits
+        .iter()
+        .find(|h| matches!(&h.citation, Citation::Code { .. }))
+        .expect("at least one Citation::Code hit for 'add'");
+
+    match &h.citation {
+        Citation::Code {
+            lang,
+            symbol,
+            line_start,
+            ..
+        } => {
+            assert_eq!(
+                lang.as_deref(),
+                Some("rust"),
+                "citation.lang must be 'rust'"
+            );
+            assert_eq!(
+                symbol.as_deref(),
+                Some("add"),
+                "citation.symbol must be 'add'"
+            );
+            assert!(*line_start >= 1, "line_start must be ≥1");
+        }
+        _ => unreachable!(),
+    }
+
+    assert_eq!(
+        h.code_lang.as_deref(),
+        Some("rust"),
+        "SearchHit.code_lang must be 'rust'"
+    );
+}
+
+/// p10-1A-2 Task 8b: a code search hit must carry `SearchHit.repo` filled
+/// from the document's `Metadata.repo` (which is set by `detect_repo` during
+/// ingest). `detect_repo` returns the name of the directory that contains
+/// `.git/`, so we `git init` the workspace root before ingesting and then
+/// assert that `h.repo == Some("workspace")`.
+#[test]
+fn rust_code_search_hit_has_repo() {
+    let env = TestEnv::lexical_only();
+
+    // `detect_repo` walks up from the file looking for `.git/`.
+    // Initialise a bare git repo at the workspace root so it is
+    // discoverable. We only need the `.git/` directory — no commits
+    // required.
+    let git_status = std::process::Command::new("git")
+        .args(["init", "--quiet"])
+        .arg(env.workspace_root.as_os_str())
+        .status()
+        .expect("git init");
+    assert!(git_status.success(), "git init must succeed");
+
+    std::fs::write(
+        env.workspace_root.join("repo_demo.rs"),
+        "/// multiplies two integers\npub fn mul(a: i32, b: i32) -> i32 {\n    a * b\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:?}");
+
+    let hits = kebab_app::search_with_config(env.config.clone(), lexical_query("mul"))
+        .expect("search must succeed");
+
+    let h = hits
+        .iter()
+        .find(|h| matches!(&h.citation, Citation::Code { .. }))
+        .expect("at least one Citation::Code hit for 'mul'");
+
+    // The workspace root directory is named "workspace" by `TestEnv`.
+    let expected_repo = env
+        .workspace_root
+        .file_name()
+        .and_then(|n| n.to_str())
+        .map(str::to_owned);
+    assert_eq!(
+        h.repo,
+        expected_repo,
+        "SearchHit.repo must match the workspace dir name (detect_repo result)"
+    );
+    // Also sanity-check code_lang is still filled.
+    assert_eq!(
+        h.code_lang.as_deref(),
+        Some("rust"),
+        "SearchHit.code_lang must be 'rust'"
+    );
+}
+
+/// p10-1b Task G: a `.py` file in a sub-directory is ingested and the
+/// resulting `Citation::Code` hit must carry `lang="python"`,
+/// `symbol="kebab_eval.metrics.compute_mrr"`, and `line_start >= 1`.
+/// The sub-directory (`kebab_eval/`) ensures `module_path_for_python`
+/// produces a non-empty prefix so the fully-qualified symbol assertion
+/// exercises the prefix wiring end-to-end.
+#[test]
+fn python_file_ingests_and_searches_as_code_citation() {
+    let env = TestEnv::lexical_only();
+
+    let module_dir = env.workspace_root.join("kebab_eval");
+    std::fs::create_dir_all(&module_dir).unwrap();
+    std::fs::write(
+        module_dir.join("metrics.py"),
+        "\"\"\"compute metrics.\"\"\"\ndef compute_mrr(scores):\n    return sum(scores) / max(len(scores), 1)\n",
+    )
+    .unwrap();
+
+    let report =
+        kebab_app::ingest_with_config(env.config.clone(), env.scope(), false)
+            .expect("ingest must succeed");
+
+    assert!(report.new >= 1, "python file ingested: {report:?}");
+
+    let items = report.items.as_ref().expect("items present");
+    let py_item = items
+        .iter()
+        .find(|i| i.doc_path.0.ends_with("metrics.py"))
+        .expect("metrics.py item");
+    assert_eq!(
+        py_item.parser_version.as_ref().map(|p| p.0.as_str()),
+        Some("code-python-v1"),
+        "parser_version must be code-python-v1"
+    );
+    assert_eq!(
+        py_item.chunker_version.as_ref().map(|c| c.0.as_str()),
+        Some("code-python-ast-v1"),
+        "chunker_version must be code-python-ast-v1"
+    );
+
+    let hits = kebab_app::search_with_config(env.config.clone(), lexical_query("compute_mrr"))
+        .expect("search must succeed");
+
+    let h = hits
+        .iter()
+        .find(|h| matches!(&h.citation, Citation::Code { .. }))
+        .expect("at least one Citation::Code hit for 'compute_mrr'");
+
+    match &h.citation {
+        Citation::Code {
+            lang,
+            symbol,
+            line_start,
+            ..
+        } => {
+            assert_eq!(
+                lang.as_deref(),
+                Some("python"),
+                "citation.lang must be 'python'"
+            );
+            assert_eq!(
+                symbol.as_deref(),
+                Some("kebab_eval.metrics.compute_mrr"),
+                "citation.symbol must be 'kebab_eval.metrics.compute_mrr'"
+            );
+            assert!(*line_start >= 1, "line_start must be >=1");
+        }
+        _ => unreachable!(),
+    }
+
+    assert_eq!(
+        h.code_lang.as_deref(),
+        Some("python"),
+        "SearchHit.code_lang must be 'python'"
+    );
+}
+
+/// p10-1b Task J: a `.ts` file in a sub-directory is ingested and the
+/// resulting `Citation::Code` hit must carry `lang="typescript"`,
+/// `symbol="src/Foo.Foo.bar"`, and `line_start >= 1`.
+/// The sub-directory (`src/`) ensures `module_path_for_tsjs` produces
+/// a non-empty prefix so the fully-qualified symbol assertion exercises
+/// the prefix wiring end-to-end.
+#[test]
+fn typescript_file_ingests_and_searches_as_code_citation() {
+    let env = TestEnv::lexical_only();
+
+    let src_dir = env.workspace_root.join("src");
+    std::fs::create_dir_all(&src_dir).unwrap();
+    std::fs::write(
+        src_dir.join("Foo.ts"),
+        "export class Foo {\n    bar(): number { return 42; }\n}\n",
+    )
+    .unwrap();
+
+    let report =
+        kebab_app::ingest_with_config(env.config.clone(), env.scope(), false)
+            .expect("ingest must succeed");
+
+    assert!(report.new >= 1, "ts file ingested: {report:?}");
+
+    let items = report.items.as_ref().expect("items present");
+    let ts_item = items
+        .iter()
+        .find(|i| i.doc_path.0.ends_with("Foo.ts"))
+        .expect("Foo.ts item");
+    assert_eq!(
+        ts_item.parser_version.as_ref().map(|p| p.0.as_str()),
+        Some("code-ts-v1"),
+        "parser_version must be code-ts-v1"
+    );
+    assert_eq!(
+        ts_item.chunker_version.as_ref().map(|c| c.0.as_str()),
+        Some("code-ts-ast-v1"),
+        "chunker_version must be code-ts-ast-v1"
+    );
+
+    let hits = kebab_app::search_with_config(env.config.clone(), lexical_query("bar"))
+        .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("typescript"),
+                "citation.lang must be 'typescript'"
+            );
+            assert_eq!(
+                symbol.as_deref(),
+                Some("src/Foo.Foo.bar"),
+                "citation.symbol must be 'src/Foo.Foo.bar'"
+            );
+            assert!(*line_start >= 1, "line_start must be >=1");
+        }
+        _ => unreachable!(),
+    }
+
+    assert_eq!(
+        h.code_lang.as_deref(),
+        Some("typescript"),
+        "SearchHit.code_lang must be 'typescript'"
+    );
+}
+
+/// p10-1b Task L: a `.js` file in a sub-directory is ingested and the
+/// resulting `Citation::Code` hit must carry `lang="javascript"`,
+/// `symbol="src/Bar.Bar.baz"`, and `line_start >= 1`.
+/// The sub-directory (`src/`) ensures `module_path_for_tsjs` produces
+/// a non-empty prefix so the fully-qualified symbol assertion exercises
+/// the prefix wiring end-to-end.
+#[test]
+fn javascript_file_ingests_and_searches_as_code_citation() {
+    let env = TestEnv::lexical_only();
+
+    let src_dir = env.workspace_root.join("src");
+    std::fs::create_dir_all(&src_dir).unwrap();
+    std::fs::write(
+        src_dir.join("Bar.js"),
+        "export class Bar {\n    baz() { return 7; }\n}\n",
+    )
+    .unwrap();
+
+    let report =
+        kebab_app::ingest_with_config(env.config.clone(), env.scope(), false)
+            .expect("ingest must succeed");
+
+    assert!(report.new >= 1, "js file ingested: {report:?}");
+
+    let items = report.items.as_ref().expect("items present");
+    let js_item = items
+        .iter()
+        .find(|i| i.doc_path.0.ends_with("Bar.js"))
+        .expect("Bar.js item");
+    assert_eq!(
+        js_item.parser_version.as_ref().map(|p| p.0.as_str()),
+        Some("code-js-v1"),
+        "parser_version must be code-js-v1"
+    );
+    assert_eq!(
+        js_item.chunker_version.as_ref().map(|c| c.0.as_str()),
+        Some("code-js-ast-v1"),
+        "chunker_version must be code-js-ast-v1"
+    );
+
+    let hits = kebab_app::search_with_config(env.config.clone(), lexical_query("baz"))
+        .expect("search must succeed");
+
+    let h = hits
+        .iter()
+        .find(|h| matches!(&h.citation, Citation::Code { .. }))
+        .expect("at least one Citation::Code hit for 'baz'");
+
+    match &h.citation {
+        Citation::Code {
+            lang,
+            symbol,
+            line_start,
+            ..
+        } => {
+            assert_eq!(
+                lang.as_deref(),
+                Some("javascript"),
+                "citation.lang must be 'javascript'"
+            );
+            assert_eq!(
+                symbol.as_deref(),
+                Some("src/Bar.Bar.baz"),
+                "citation.symbol must be 'src/Bar.Bar.baz'"
+            );
+            assert!(*line_start >= 1, "line_start must be >=1");
+        }
+        _ => unreachable!(),
+    }
+
+    assert_eq!(
+        h.code_lang.as_deref(),
+        Some("javascript"),
+        "SearchHit.code_lang must be 'javascript'"
+    );
+}
+
+/// Re-ingesting the same `.rs` file without changes must report
+/// `Unchanged` (incremental-skip path exercised).
+#[test]
+fn rust_file_re_ingest_is_unchanged() {
+    let env = TestEnv::lexical_only();
+
+    std::fs::write(
+        env.workspace_root.join("stable.rs"),
+        "pub fn noop() {}\n",
+    )
+    .unwrap();
+
+    let r1 =
+        kebab_app::ingest_with_config(env.config.clone(), env.scope(), false).unwrap();
+    let item1 = r1
+        .items
+        .as_ref()
+        .unwrap()
+        .iter()
+        .find(|i| i.doc_path.0.ends_with("stable.rs"))
+        .cloned()
+        .unwrap();
+    assert_eq!(item1.kind, IngestItemKind::New);
+
+    let r2 =
+        kebab_app::ingest_with_config(env.config.clone(), env.scope(), false).unwrap();
+    let item2 = r2
+        .items
+        .unwrap()
+        .into_iter()
+        .find(|i| i.doc_path.0.ends_with("stable.rs"))
+        .unwrap();
+    assert_eq!(
+        item2.kind,
+        IngestItemKind::Unchanged,
+        "identical bytes → Unchanged"
+    );
+    assert_eq!(item2.doc_id, item1.doc_id);
+}

crates/kebab-app/tests/common/mod.rs

@@ -79,6 +79,37 @@ impl TestEnv {
             ..Default::default()
         }
     }
+
+    /// p9-fb-34 alias — tests added in fb-34 invoke `TestEnv::new()`
+    /// per the plan; route to the existing lexical-only constructor
+    /// so the lane stays AVX-free without churning all the existing
+    /// callers.
+    pub fn new() -> Self {
+        Self::lexical_only()
+    }
+
+    /// p9-fb-34: open a fresh `App` against this env's config. Used
+    /// by integration tests that need to call `App::search_with_opts`
+    /// directly. Caller can invoke this multiple times to simulate
+    /// re-opening the binary after a corpus revision bump.
+    pub fn app(&self) -> kebab_app::App {
+        kebab_app::App::open_with_config(self.config.clone())
+            .expect("App::open_with_config")
+    }
+}
+
+/// p9-fb-34: write `content` into the env's workspace at
+/// `relative_path`, then run a full ingest so the document is
+/// searchable. Mirrors the convenience helpers used by other
+/// `TestEnv`-driven crates.
+pub fn ingest_md(env: &TestEnv, relative_path: &str, content: &str) {
+    let path = env.workspace_root.join(relative_path);
+    if let Some(parent) = path.parent() {
+        std::fs::create_dir_all(parent).expect("create parent dirs");
+    }
+    std::fs::write(&path, content).expect("write workspace file");
+    kebab_app::ingest_with_config(env.config.clone(), env.scope(), true)
+        .expect("ingest_with_config");
 }
 
 /// Test helper: build a `SearchQuery` for lexical mode at k=10. Used
@@ -94,6 +125,29 @@ pub fn lexical_query(text: &str) -> kebab_core::SearchQuery {
     }
 }
 
+/// p9-fb-32: rewrite `documents.updated_at` for one workspace path
+/// to `now - days_ago` (RFC3339 UTC). Used by staleness integration
+/// tests to simulate aged-out docs without faking system time. Caller
+/// is responsible for ingesting the doc *before* calling this — the
+/// row must already exist.
+pub fn backdate_document_updated_at(env: &TestEnv, workspace_path: &str, days_ago: i64) {
+    let backdated = (time::OffsetDateTime::now_utc() - time::Duration::days(days_ago))
+        .format(&time::format_description::well_known::Rfc3339)
+        .expect("format backdated updated_at");
+    let db_path = PathBuf::from(&env.config.storage.data_dir).join("kebab.sqlite");
+    let conn = rusqlite::Connection::open(&db_path).expect("open kebab.sqlite");
+    let updated = conn
+        .execute(
+            "UPDATE documents SET updated_at = ?1 WHERE workspace_path = ?2",
+            rusqlite::params![backdated, workspace_path],
+        )
+        .expect("UPDATE documents.updated_at");
+    assert_eq!(
+        updated, 1,
+        "backdate_document_updated_at: expected to update exactly 1 row for {workspace_path}, got {updated}"
+    );
+}
+
 fn copy_fixture_workspace(dest: &Path) {
     let src = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
         .join("tests")

crates/kebab-app/tests/cursor.rs

@@ -0,0 +1,24 @@
+//! p9-fb-34: cursor encode/decode round-trip + corpus_revision mismatch.
+
+use kebab_app::cursor;
+
+#[test]
+fn cursor_roundtrip_preserves_offset() {
+    let encoded = cursor::encode(5, "rev-abc");
+    let offset = cursor::decode(&encoded, "rev-abc").unwrap();
+    assert_eq!(offset, 5);
+}
+
+#[test]
+fn cursor_decode_rejects_mismatched_revision() {
+    let encoded = cursor::encode(7, "rev-old");
+    let err = cursor::decode(&encoded, "rev-new").unwrap_err();
+    assert_eq!(err.code, "stale_cursor");
+    assert!(err.message.contains("rev-old") || err.message.contains("rev-new"));
+}
+
+#[test]
+fn cursor_decode_rejects_garbage_input() {
+    let err = cursor::decode("not-base64!!!", "any").unwrap_err();
+    assert_eq!(err.code, "stale_cursor");
+}

crates/kebab-app/tests/fetch_integration.rs

@@ -0,0 +1,329 @@
+//! p9-fb-35 App::fetch integration tests.
+
+mod common;
+
+use kebab_app::App;
+use kebab_core::{FetchKind, FetchOpts, FetchQuery};
+
+fn open(env: &common::TestEnv) -> App {
+    env.app()
+}
+
+#[test]
+fn fetch_chunk_returns_target_only_when_no_context() {
+    let env = common::TestEnv::new();
+    common::ingest_md(&env, "a.md", "# Title\n\nFirst paragraph.\n\n## Section\n\nSecond.\n");
+    let app = open(&env);
+
+    // Find a chunk via search to obtain its id.
+    let q = kebab_core::SearchQuery {
+        text: "First".to_string(),
+        mode: kebab_core::SearchMode::Lexical,
+        k: 1,
+        filters: kebab_core::SearchFilters::default(),
+    };
+    let hits = app.search(q).unwrap();
+    let chunk_id = hits[0].chunk_id.clone();
+
+    let result = app
+        .fetch(FetchQuery::Chunk(chunk_id), FetchOpts::default())
+        .unwrap();
+    assert_eq!(result.kind, FetchKind::Chunk);
+    assert!(result.chunk.is_some(), "target chunk populated");
+    assert!(result.context_before.is_empty());
+    assert!(result.context_after.is_empty());
+    assert!(!result.truncated);
+}
+
+#[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";
+    common::ingest_md(&env, "multi.md", body);
+    let app = env.app();
+
+    let q = kebab_core::SearchQuery {
+        text: "A3".to_string(),
+        mode: kebab_core::SearchMode::Lexical,
+        k: 1,
+        filters: kebab_core::SearchFilters::default(),
+    };
+    let hits = app.search(q).unwrap();
+    let chunk_id = hits[0].chunk_id.clone();
+
+    let result = app
+        .fetch(
+            FetchQuery::Chunk(chunk_id),
+            FetchOpts {
+                context: Some(2),
+                max_tokens: None,
+            },
+        )
+        .unwrap();
+    assert_eq!(result.kind, FetchKind::Chunk);
+    assert!(result.chunk.is_some());
+    let total = result.context_before.len() + result.context_after.len();
+    assert!(total >= 1, "at least one neighbor expected");
+    assert!(total <= 4, "context capped at +-2 ⇒ max 4 neighbors");
+}
+
+#[test]
+fn fetch_chunk_unknown_id_returns_chunk_not_found() {
+    let env = common::TestEnv::new();
+    let app = env.app();
+    let err = app
+        .fetch(
+            FetchQuery::Chunk(kebab_core::ChunkId("nonexistent-id".to_string())),
+            FetchOpts::default(),
+        )
+        .unwrap_err();
+    let msg = err.to_string();
+    assert!(
+        msg.contains("chunk_not_found") || msg.contains("nonexistent-id"),
+        "expected chunk_not_found error, got: {msg}"
+    );
+}
+
+#[test]
+fn fetch_doc_returns_serialized_markdown() {
+    let env = common::TestEnv::new();
+    let body = "# Heading One\n\nFirst paragraph.\n\n## Sub\n\nSecond.\n";
+    common::ingest_md(&env, "doc.md", body);
+    let app = env.app();
+
+    // Discover doc_id via search hit (avoids depending on list_docs API shape).
+    let q = kebab_core::SearchQuery {
+        text: "First".to_string(),
+        mode: kebab_core::SearchMode::Lexical,
+        k: 1,
+        filters: kebab_core::SearchFilters::default(),
+    };
+    let hits = app.search(q).unwrap();
+    let doc_id = hits[0].doc_id.clone();
+
+    let result = app
+        .fetch(FetchQuery::Doc(doc_id), FetchOpts::default())
+        .unwrap();
+    assert_eq!(result.kind, FetchKind::Doc);
+    let text = result.text.expect("doc text");
+    assert!(text.contains("Heading One"), "doc text contains heading: {text:?}");
+    assert!(text.contains("First paragraph"), "doc text contains body");
+    assert!(!result.truncated);
+}
+
+#[test]
+fn fetch_doc_unknown_id_returns_doc_not_found() {
+    let env = common::TestEnv::new();
+    let app = env.app();
+    let err = app
+        .fetch(
+            FetchQuery::Doc(kebab_core::DocumentId("nonexistent-doc".to_string())),
+            FetchOpts::default(),
+        )
+        .unwrap_err();
+    assert!(err.to_string().contains("doc_not_found"), "got: {err}");
+}
+
+#[test]
+fn fetch_doc_with_max_tokens_truncates() {
+    let env = common::TestEnv::new();
+    let p = "Lorem ipsum dolor sit amet consectetur adipiscing elit. ".repeat(20);
+    let body = format!("# Big\n\n{p}\n");
+    common::ingest_md(&env, "big.md", &body);
+    let app = env.app();
+    let q = kebab_core::SearchQuery {
+        text: "Lorem".to_string(),
+        mode: kebab_core::SearchMode::Lexical,
+        k: 1,
+        filters: kebab_core::SearchFilters::default(),
+    };
+    let hits = app.search(q).unwrap();
+    let doc_id = hits[0].doc_id.clone();
+
+    let result = app
+        .fetch(
+            FetchQuery::Doc(doc_id),
+            FetchOpts {
+                context: None,
+                max_tokens: Some(20), // ~80 chars
+            },
+        )
+        .unwrap();
+    assert!(result.truncated);
+    let text = result.text.expect("doc text");
+    assert!(text.chars().count() <= 100, "trimmed text len {}", text.chars().count());
+}
+
+#[test]
+fn fetch_span_returns_line_range() {
+    let env = common::TestEnv::new();
+    // Use a list so the canonical-to-markdown roundtrip emits 5
+    // single-line entries joined by `\n` (paragraphs would be joined by
+    // `\n\n`, and CommonMark soft breaks inside one paragraph collapse to
+    // spaces — see crates/kebab-parse-md/src/blocks.rs `Event::SoftBreak`).
+    let body = "- Line one.\n- Line two.\n- Line three.\n- Line four.\n- Line five.\n";
+    common::ingest_md(&env, "lines.md", body);
+    let app = env.app();
+
+    let q = kebab_core::SearchQuery {
+        text: "Line".to_string(),
+        mode: kebab_core::SearchMode::Lexical,
+        k: 1,
+        filters: kebab_core::SearchFilters::default(),
+    };
+    let hits = app.search(q).unwrap();
+    let doc_id = hits[0].doc_id.clone();
+
+    let result = app
+        .fetch(
+            FetchQuery::Span {
+                doc_id,
+                line_start: 2,
+                line_end: 4,
+            },
+            FetchOpts::default(),
+        )
+        .unwrap();
+    assert_eq!(result.kind, FetchKind::Span);
+    let text = result.text.expect("span text");
+    let line_count = text.lines().count();
+    assert_eq!(line_count, 3, "span should be 3 lines: {text:?}");
+    assert_eq!(result.line_start, Some(2));
+    assert_eq!(result.line_end, Some(4));
+    assert_eq!(result.effective_end, Some(4));
+    assert!(!result.truncated);
+}
+
+#[test]
+fn fetch_span_clamps_line_end_when_out_of_range() {
+    let env = common::TestEnv::new();
+    common::ingest_md(&env, "short.md", "Line one.\nLine two.\n");
+    let app = env.app();
+    let q = kebab_core::SearchQuery {
+        text: "Line".to_string(),
+        mode: kebab_core::SearchMode::Lexical,
+        k: 1,
+        filters: kebab_core::SearchFilters::default(),
+    };
+    let hits = app.search(q).unwrap();
+    let doc_id = hits[0].doc_id.clone();
+
+    let result = app
+        .fetch(
+            FetchQuery::Span {
+                doc_id,
+                line_start: 1,
+                line_end: 999,
+            },
+            FetchOpts::default(),
+        )
+        .unwrap();
+    let text = result.text.expect("span text");
+    let actual_lines = text.lines().count();
+    assert_eq!(result.effective_end, Some(actual_lines as u32));
+    assert!(actual_lines < 999);
+}
+
+#[test]
+fn fetch_span_invalid_input_when_zero_lines() {
+    let env = common::TestEnv::new();
+    common::ingest_md(&env, "a.md", "Line one.\n");
+    let app = env.app();
+    let q = kebab_core::SearchQuery {
+        text: "Line".to_string(),
+        mode: kebab_core::SearchMode::Lexical,
+        k: 1,
+        filters: kebab_core::SearchFilters::default(),
+    };
+    let hits = app.search(q).unwrap();
+    let doc_id = hits[0].doc_id.clone();
+
+    let err = app
+        .fetch(
+            FetchQuery::Span {
+                doc_id,
+                line_start: 0,
+                line_end: 0,
+            },
+            FetchOpts::default(),
+        )
+        .unwrap_err();
+    assert!(err.to_string().contains("invalid_input"), "got: {err}");
+}
+
+#[test]
+fn fetch_span_line_start_beyond_total_returns_empty_text() {
+    let env = common::TestEnv::new();
+    let body = "- Line one.\n- Line two.\n";
+    common::ingest_md(&env, "two_lines.md", body);
+    let app = env.app();
+    let q = kebab_core::SearchQuery {
+        text: "Line".to_string(),
+        mode: kebab_core::SearchMode::Lexical,
+        k: 1,
+        filters: kebab_core::SearchFilters::default(),
+    };
+    let hits = app.search(q).unwrap();
+    let doc_id = hits[0].doc_id.clone();
+
+    let result = app
+        .fetch(
+            FetchQuery::Span {
+                doc_id,
+                line_start: 100,
+                line_end: 200,
+            },
+            FetchOpts::default(),
+        )
+        .unwrap();
+    let text = result.text.expect("text field");
+    assert!(text.is_empty(), "out-of-range request returns empty text");
+    assert!(
+        !result.truncated,
+        "out-of-range is NOT truncated (budget-only flag)"
+    );
+}
+
+#[test]
+fn fetch_chunk_context_at_first_chunk_clamps_lower_bound() {
+    let env = common::TestEnv::new();
+    // Multi-chunk markdown so context ±N has neighbors.
+    let body =
+        "# H1\n\nFirst chunk text body.\n\n# H2\n\nSecond chunk.\n\n# H3\n\nThird chunk.\n";
+    common::ingest_md(&env, "boundary.md", body);
+    let app = env.app();
+    let q = kebab_core::SearchQuery {
+        text: "First".to_string(),
+        mode: kebab_core::SearchMode::Lexical,
+        k: 1,
+        filters: kebab_core::SearchFilters::default(),
+    };
+    let hits = app.search(q).unwrap();
+    let chunk_id = hits[0].chunk_id.clone();
+
+    let result = app
+        .fetch(
+            FetchQuery::Chunk(chunk_id),
+            FetchOpts {
+                context: Some(2),
+                max_tokens: None,
+            },
+        )
+        .unwrap();
+    // p9-fb-35 R2: doc has 3 chunks; ±2 should clamp the total
+    // neighbor count to ≤ 2 + 1 (= excludes target).
+    //
+    // ⚠ Strict "first-chunk → context_before is empty" cannot be
+    // asserted here yet because chunks.ordinal column does not exist
+    // — `list_chunk_ids_for_doc` orders by `(created_at, chunk_id)`
+    // and chunk_id is a blake3 hash, so the "First chunk" content
+    // may land at any hash-order position within the doc. The clamp
+    // logic itself is correct (target_idx ± n → [0..len]); we just
+    // can't pin which chunk is hash-order-first. Tracked as
+    // follow-up: V007 chunks.ordinal migration.
+    let total = result.context_before.len() + result.context_after.len();
+    assert!(
+        total <= 2,
+        "doc with 3 chunks ±2 → at most 2 neighbors (excludes target), got {total}"
+    );
+}

crates/kebab-app/tests/file_deletion_auto_purge.rs

@@ -0,0 +1,178 @@
+//! Dogfood: auto-purge stored docs for filesystem-deleted files.
+//!
+//! Two tests:
+//!
+//! 1. `file_deletion_auto_purge` — ingest 2 files, delete one, re-ingest.
+//!    The re-ingest must report `purged_deleted_files = 1`, the deleted
+//!    file must no longer appear in `list_docs`, and lexical search for
+//!    its unique content must return no hits.
+//!
+//! 2. `include_scope_narrowing_does_not_purge` — ingest 2 files under a
+//!    wide glob, narrow the walker scope to only one file, re-ingest.
+//!    The narrowed ingest must NOT purge the out-of-scope file because
+//!    the file is still on disk (just excluded from this run). Protects
+//!    users against accidental data loss via config edits.
+
+mod common;
+
+use common::TestEnv;
+use kebab_app::ingest_with_config_opts;
+use kebab_app::IngestOpts;
+use kebab_core::{DocFilter, DocumentStore, SearchMode, SearchQuery, SourceScope};
+
+/// Helper: open the store via `TestEnv` and run `list_documents`.
+fn list_doc_paths(env: &TestEnv) -> Vec<String> {
+    use kebab_store_sqlite::SqliteStore;
+    let store = SqliteStore::open(&env.config).unwrap();
+    store.run_migrations().unwrap();
+    store
+        .list_documents(&DocFilter::default())
+        .unwrap()
+        .into_iter()
+        .map(|d| d.doc_path.0)
+        .collect()
+}
+
+#[test]
+fn file_deletion_auto_purge() {
+    let env = TestEnv::lexical_only();
+
+    // Write two .rs files into the workspace.
+    let a_path = env.workspace_root.join("a.rs");
+    let b_path = env.workspace_root.join("b.rs");
+    std::fs::write(&a_path, "// file a\nfn alpha() {}\n").unwrap();
+    std::fs::write(&b_path, "// file b\nfn bravo() {}\n").unwrap();
+
+    // First ingest — both must be New.
+    let first = ingest_with_config_opts(
+        env.config.clone(),
+        env.scope(),
+        false,
+        IngestOpts::default(),
+    )
+    .expect("first ingest must succeed");
+    // Only count the .rs files we added (there may be fixture files too).
+    let first_new = first.new;
+    assert!(first_new >= 2, "expected at least 2 new docs: {first:?}");
+    assert_eq!(
+        first.purged_deleted_files, 0,
+        "no purges on first ingest: {first:?}"
+    );
+    assert_eq!(first.errors, 0, "no errors on first ingest: {first:?}");
+
+    // Delete one file from the filesystem.
+    std::fs::remove_file(&b_path).expect("remove b.rs");
+
+    // Second ingest — scanned count drops by 1; b.rs should be purged.
+    let second = ingest_with_config_opts(
+        env.config.clone(),
+        env.scope(),
+        false,
+        IngestOpts::default(),
+    )
+    .expect("second ingest must succeed");
+
+    assert_eq!(
+        second.purged_deleted_files, 1,
+        "exactly 1 file should be purged: {second:?}"
+    );
+    assert_eq!(second.new, 0, "no new docs after deletion: {second:?}");
+    assert_eq!(second.updated, 0, "no updated docs: {second:?}");
+    assert_eq!(second.errors, 0, "no errors: {second:?}");
+
+    // b.rs must no longer appear in list_docs.
+    let doc_paths = list_doc_paths(&env);
+    let b_ws_path = "b.rs";
+    assert!(
+        !doc_paths.iter().any(|p| p == b_ws_path),
+        "b.rs must be gone from list_docs; got: {doc_paths:?}"
+    );
+    // a.rs must still be present.
+    let a_ws_path = "a.rs";
+    assert!(
+        doc_paths.iter().any(|p| p == a_ws_path),
+        "a.rs must still be in list_docs; got: {doc_paths:?}"
+    );
+
+    // Lexical search for b.rs's unique content returns no hits.
+    let app = env.app();
+    let query = SearchQuery {
+        text: "bravo".to_string(),
+        mode: SearchMode::Lexical,
+        k: 10,
+        filters: kebab_core::SearchFilters::default(),
+    };
+    let hits = app.search(query).expect("search must not error");
+    assert!(
+        hits.is_empty(),
+        "search for deleted file's content must return no hits; got: {hits:?}"
+    );
+}
+
+#[test]
+fn include_scope_narrowing_does_not_purge() {
+    let env = TestEnv::lexical_only();
+
+    // Write two .rs files.
+    let a_path = env.workspace_root.join("a_narrow.rs");
+    let b_path = env.workspace_root.join("b_narrow.rs");
+    std::fs::write(&a_path, "// narrow a\nfn alpha_narrow() {}\n").unwrap();
+    std::fs::write(&b_path, "// narrow b\nfn bravo_narrow() {}\n").unwrap();
+
+    // Wide scope: first ingest — both must be New.
+    let wide_scope = SourceScope {
+        root: env.workspace_root.clone(),
+        include: vec!["**/*.rs".to_string()],
+        exclude: env.config.workspace.exclude.clone(),
+    };
+    let first = ingest_with_config_opts(
+        env.config.clone(),
+        wide_scope,
+        false,
+        IngestOpts::default(),
+    )
+    .expect("first ingest (wide) must succeed");
+    assert!(
+        first.new >= 2,
+        "expected at least 2 new docs: {first:?}"
+    );
+    assert_eq!(
+        first.purged_deleted_files, 0,
+        "no purges on first ingest: {first:?}"
+    );
+
+    // Narrow scope: only a_narrow.rs in include — b_narrow.rs is still
+    // on disk but excluded from the walker scope.
+    let narrow_scope = SourceScope {
+        root: env.workspace_root.clone(),
+        include: vec!["a_narrow.rs".to_string()],
+        exclude: env.config.workspace.exclude.clone(),
+    };
+    let second = ingest_with_config_opts(
+        env.config.clone(),
+        narrow_scope,
+        false,
+        IngestOpts::default(),
+    )
+    .expect("second ingest (narrow) must succeed");
+
+    // CRITICAL: b_narrow.rs is still on disk — must NOT be purged.
+    assert_eq!(
+        second.purged_deleted_files, 0,
+        "scope-narrowing must NOT purge on-disk files; got: {second:?}"
+    );
+    assert_eq!(second.errors, 0, "no errors: {second:?}");
+
+    // b_narrow.rs must still exist in the store.
+    let doc_paths = list_doc_paths(&env);
+    let b_ws_path = "b_narrow.rs";
+    assert!(
+        doc_paths.iter().any(|p| p == b_ws_path),
+        "b_narrow.rs must still be in list_docs after scope narrowing; got: {doc_paths:?}"
+    );
+    // And the file must still be on disk.
+    assert!(
+        b_path.exists(),
+        "b_narrow.rs must still be on disk (we didn't delete it)"
+    );
+}

crates/kebab-app/tests/ingest_file.rs

@@ -0,0 +1,111 @@
+//! Integration: kebab_app::ingest_file_with_config copies external file
+//! to _external/, ingests as single asset, idempotent on second call.
+
+use std::fs;
+
+use kebab_config::Config;
+
+#[test]
+fn ingest_file_copies_external_md_and_reports_new() {
+    let dir = tempfile::tempdir().unwrap();
+    let workspace = dir.path().join("notes");
+    let data = dir.path().join("data");
+    fs::create_dir_all(&workspace).unwrap();
+    fs::create_dir_all(&data).unwrap();
+
+    let mut cfg = Config::defaults();
+    cfg.workspace.root = workspace.to_string_lossy().into_owned();
+    cfg.storage.data_dir = data.to_string_lossy().into_owned();
+    cfg.models.embedding.provider = "none".to_string();
+    cfg.models.embedding.dimensions = 0;
+
+    // Source file outside the workspace.
+    let external_src = dir.path().join("source.md");
+    fs::write(&external_src, "# Hello\n\nbody.").unwrap();
+
+    let report = kebab_app::ingest_file_with_config(cfg.clone(), &external_src).unwrap();
+    assert_eq!(report.scanned, 1, "{report:?}");
+    assert_eq!(report.new, 1, "{report:?}");
+    assert_eq!(report.unchanged, 0, "{report:?}");
+
+    // _external/ dir created, file copied with hash prefix.
+    let ext_dir = workspace.join("_external");
+    assert!(ext_dir.is_dir());
+    let entries: Vec<_> = fs::read_dir(&ext_dir)
+        .unwrap()
+        .filter_map(|e| e.ok())
+        .collect();
+    assert_eq!(entries.len(), 1, "exactly one file in _external/");
+    let name = entries[0].file_name().to_string_lossy().into_owned();
+    assert!(name.ends_with(".md"));
+
+    // .kebabignore has _external/ line.
+    let ki = fs::read_to_string(workspace.join(".kebabignore")).unwrap();
+    assert!(ki.lines().any(|l| l.trim() == "_external/"));
+}
+
+#[test]
+fn ingest_file_idempotent_on_second_call() {
+    let dir = tempfile::tempdir().unwrap();
+    let workspace = dir.path().join("notes");
+    let data = dir.path().join("data");
+    fs::create_dir_all(&workspace).unwrap();
+    fs::create_dir_all(&data).unwrap();
+
+    let mut cfg = Config::defaults();
+    cfg.workspace.root = workspace.to_string_lossy().into_owned();
+    cfg.storage.data_dir = data.to_string_lossy().into_owned();
+    cfg.models.embedding.provider = "none".to_string();
+    cfg.models.embedding.dimensions = 0;
+
+    let src = dir.path().join("doc.md");
+    fs::write(&src, "# A\n\nbody.").unwrap();
+
+    let r1 = kebab_app::ingest_file_with_config(cfg.clone(), &src).unwrap();
+    assert_eq!(r1.new, 1);
+
+    let r2 = kebab_app::ingest_file_with_config(cfg.clone(), &src).unwrap();
+    assert_eq!(r2.new, 0, "{r2:?}");
+    assert_eq!(r2.unchanged, 1, "{r2:?}");
+}
+
+#[test]
+fn ingest_file_errors_on_missing_path() {
+    let dir = tempfile::tempdir().unwrap();
+    let workspace = dir.path().join("notes");
+    let data = dir.path().join("data");
+    fs::create_dir_all(&workspace).unwrap();
+    fs::create_dir_all(&data).unwrap();
+
+    let mut cfg = Config::defaults();
+    cfg.workspace.root = workspace.to_string_lossy().into_owned();
+    cfg.storage.data_dir = data.to_string_lossy().into_owned();
+    cfg.models.embedding.provider = "none".to_string();
+    cfg.models.embedding.dimensions = 0;
+
+    let nonexistent = dir.path().join("nope.md");
+    let err = kebab_app::ingest_file_with_config(cfg, &nonexistent).unwrap_err();
+    assert!(err.to_string().contains("does not exist"), "{err}");
+}
+
+#[test]
+fn ingest_file_errors_on_unsupported_extension() {
+    let dir = tempfile::tempdir().unwrap();
+    let workspace = dir.path().join("notes");
+    let data = dir.path().join("data");
+    fs::create_dir_all(&workspace).unwrap();
+    fs::create_dir_all(&data).unwrap();
+
+    let mut cfg = Config::defaults();
+    cfg.workspace.root = workspace.to_string_lossy().into_owned();
+    cfg.storage.data_dir = data.to_string_lossy().into_owned();
+    cfg.models.embedding.provider = "none".to_string();
+    cfg.models.embedding.dimensions = 0;
+
+    let docx = dir.path().join("doc.docx");
+    fs::write(&docx, b"fake docx bytes").unwrap();
+
+    let err = kebab_app::ingest_file_with_config(cfg, &docx).unwrap_err();
+    assert!(err.to_string().contains("unsupported extension"), "{err}");
+    assert!(err.to_string().contains(".docx") || err.to_string().contains("docx"), "{err}");
+}

crates/kebab-app/tests/ingest_stdin.rs

@@ -0,0 +1,78 @@
+//! Integration: kebab_app::ingest_stdin_with_config injects frontmatter,
+//! writes to _external/, ingests as single asset.
+
+use std::fs;
+
+use kebab_config::Config;
+
+fn fresh_cfg(dir: &std::path::Path) -> Config {
+    let workspace = dir.join("notes");
+    let data = dir.join("data");
+    fs::create_dir_all(&workspace).unwrap();
+    fs::create_dir_all(&data).unwrap();
+
+    let mut cfg = Config::defaults();
+    cfg.workspace.root = workspace.to_string_lossy().into_owned();
+    cfg.storage.data_dir = data.to_string_lossy().into_owned();
+    cfg.models.embedding.provider = "none".to_string();
+    cfg.models.embedding.dimensions = 0;
+    cfg
+}
+
+#[test]
+fn ingest_stdin_writes_frontmatter_and_reports_new() {
+    let dir = tempfile::tempdir().unwrap();
+    let cfg = fresh_cfg(dir.path());
+
+    let report = kebab_app::ingest_stdin_with_config(
+        cfg.clone(),
+        "## Body content\n\nMore.",
+        "Article X",
+        Some("https://example.com/x"),
+    ).unwrap();
+    assert_eq!(report.new, 1, "{report:?}");
+
+    // _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())
+        .collect();
+    assert_eq!(entries.len(), 1);
+    let content = fs::read_to_string(entries[0].path()).unwrap();
+    assert!(content.starts_with("---\n"));
+    assert!(content.contains("title: \"Article X\""));
+    assert!(content.contains("source_uri: \"https://example.com/x\""));
+    assert!(content.contains("## Body content"));
+}
+
+#[test]
+fn ingest_stdin_without_source_uri() {
+    let dir = tempfile::tempdir().unwrap();
+    let cfg = fresh_cfg(dir.path());
+
+    let report = kebab_app::ingest_stdin_with_config(
+        cfg.clone(),
+        "## Body",
+        "Title",
+        None,
+    ).unwrap();
+    assert_eq!(report.new, 1);
+
+    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())
+        .collect();
+    let content = fs::read_to_string(entries[0].path()).unwrap();
+    assert!(content.contains("title: \"Title\""));
+    assert!(!content.contains("source_uri"));
+}
+
+#[test]
+fn ingest_stdin_errors_on_existing_frontmatter() {
+    let dir = tempfile::tempdir().unwrap();
+    let cfg = fresh_cfg(dir.path());
+
+    let body = "---\ntitle: Already\n---\n\n## Body";
+    let err = kebab_app::ingest_stdin_with_config(cfg, body, "New", None).unwrap_err();
+    assert!(err.to_string().contains("already has frontmatter"), "{err}");
+}

crates/kebab-app/tests/reset_orphans.rs

@@ -0,0 +1,141 @@
+//! Integration test for `kebab reset --orphans-only`.
+//!
+//! Verifies that stored docs outside the current walker scope are purged
+//! from the store without removing any files from the filesystem.
+//!
+//! Test outline:
+//! 1. Ingest 3 .rs files (a.rs, b.rs, c.rs) — all New.
+//! 2. Narrow the config `include` to `["a.rs"]` only; b.rs and c.rs are
+//!    still on disk but outside the walker scope.
+//! 3. Run `execute(ResetScope::OrphansOnly, &cfg)` — report must show
+//!    `orphans_purged == 2` and `purged_paths` contains b.rs + c.rs.
+//! 4. `list docs` must show only a.rs.
+//! 5. b.rs and c.rs must still exist on disk (no filesystem removal).
+//! 6. Second reset → `orphans_purged == 0` (idempotent).
+
+mod common;
+
+use common::TestEnv;
+use kebab_app::IngestOpts;
+use kebab_app::reset::{ResetScope, execute};
+use kebab_core::{DocFilter, DocumentStore, SourceScope};
+
+/// Open the SqliteStore and list all `workspace_path` values.
+fn list_doc_paths(env: &TestEnv) -> Vec<String> {
+    use kebab_store_sqlite::SqliteStore;
+    let store = SqliteStore::open(&env.config).unwrap();
+    store.run_migrations().unwrap();
+    store
+        .list_documents(&DocFilter::default())
+        .unwrap()
+        .into_iter()
+        .map(|d| d.doc_path.0)
+        .collect()
+}
+
+#[test]
+fn reset_orphans_only_purges_out_of_scope_docs() {
+    let env = TestEnv::lexical_only();
+
+    // Write three .rs files into the workspace.
+    let a_path = env.workspace_root.join("a.rs");
+    let b_path = env.workspace_root.join("b.rs");
+    let c_path = env.workspace_root.join("c.rs");
+    std::fs::write(&a_path, "// file a\nfn alpha() {}\n").unwrap();
+    std::fs::write(&b_path, "// file b\nfn bravo() {}\n").unwrap();
+    std::fs::write(&c_path, "// file c\nfn charlie() {}\n").unwrap();
+
+    // Ingest all three with a wide scope.
+    let wide_scope = SourceScope {
+        root: env.workspace_root.clone(),
+        include: vec!["**/*.rs".to_string()],
+        exclude: env.config.workspace.exclude.clone(),
+    };
+    let first = kebab_app::ingest_with_config_opts(
+        env.config.clone(),
+        wide_scope,
+        false,
+        IngestOpts::default(),
+    )
+    .expect("first ingest must succeed");
+    // The fixture workspace may contain other .rs files — just assert we
+    // got at least 3 new docs (our a.rs, b.rs, c.rs).
+    assert!(first.new >= 3, "expected at least 3 new docs: {first:?}");
+    assert_eq!(first.errors, 0, "no errors on first ingest");
+
+    // Narrow config to include only a.rs; b.rs + c.rs are still on disk.
+    let mut narrow_cfg = env.config.clone();
+    narrow_cfg.workspace.exclude.clear();
+    // Re-point workspace root (already correct) and restrict include via
+    // the SourceScope in the connector. The config's `workspace.root` is
+    // used by `enumerate_orphans` to build its scope — we keep that
+    // pointing at the workspace root. We simulate narrowing by setting a
+    // glob that only matches a.rs.
+    //
+    // NOTE: `kebab_config::WorkspaceCfg` does not have an `include` field
+    // (it was removed in p9-fb-25). We narrow the scope via the walker
+    // exclude list: exclude b.rs and c.rs explicitly.
+    narrow_cfg.workspace.exclude = vec!["b.rs".to_string(), "c.rs".to_string()];
+
+    // Run orphans-only reset.
+    let report = execute(ResetScope::OrphansOnly, &narrow_cfg)
+        .expect("orphans-only reset must succeed");
+
+    assert_eq!(
+        report.orphans_purged, 2,
+        "expected 2 orphans purged (b.rs + c.rs): {report:?}"
+    );
+
+    let mut purged: Vec<String> = report
+        .purged_paths
+        .iter()
+        .map(|p| p.0.clone())
+        .collect();
+    purged.sort();
+    assert_eq!(
+        purged,
+        vec!["b.rs".to_string(), "c.rs".to_string()],
+        "purged_paths must list b.rs and c.rs in sorted order: {purged:?}"
+    );
+
+    // list docs must show only a.rs (and any pre-existing fixture files
+    // that are not excluded by the narrow config).
+    let doc_paths = list_doc_paths(&env);
+    // The narrow_cfg excludes b.rs + c.rs — they must no longer be in store.
+    assert!(
+        !doc_paths.iter().any(|p| p == "b.rs"),
+        "b.rs must be gone from store after orphans-only reset; got: {doc_paths:?}"
+    );
+    assert!(
+        !doc_paths.iter().any(|p| p == "c.rs"),
+        "c.rs must be gone from store after orphans-only reset; got: {doc_paths:?}"
+    );
+    assert!(
+        doc_paths.iter().any(|p| p == "a.rs"),
+        "a.rs must still be in store; got: {doc_paths:?}"
+    );
+
+    // Both b.rs and c.rs must still exist on the filesystem — no file
+    // removal is performed by orphans-only.
+    assert!(
+        b_path.exists(),
+        "b.rs must still be on disk after orphans-only reset"
+    );
+    assert!(
+        c_path.exists(),
+        "c.rs must still be on disk after orphans-only reset"
+    );
+
+    // Second reset must be idempotent: nothing left to purge.
+    let second = execute(ResetScope::OrphansOnly, &narrow_cfg)
+        .expect("second orphans-only reset must succeed");
+    assert_eq!(
+        second.orphans_purged, 0,
+        "second reset must be idempotent (orphans_purged == 0): {second:?}"
+    );
+    assert!(
+        second.purged_paths.is_empty(),
+        "second reset purged_paths must be empty: {:?}",
+        second.purged_paths
+    );
+}

crates/kebab-app/tests/schema_report.rs

@@ -58,6 +58,10 @@ fn schema_report_reflects_freshly_ingested_kb() {
     );
     assert!(schema.capabilities.json_mode);
     assert!(!schema.capabilities.streaming_ask);
+    assert!(
+        schema.capabilities.mcp_server,
+        "mcp_server should be true after fb-30",
+    );
     assert_eq!(
         schema.stats.doc_count, 2,
         "expected 2 docs (a.md + b.md): {:?}",

crates/kebab-app/tests/search_budget_integration.rs

@@ -0,0 +1,165 @@
+//! p9-fb-34: App::search_with_opts integration tests.
+
+mod common;
+
+use kebab_app::SearchResponse;
+use kebab_core::{SearchFilters, SearchMode, SearchOpts, SearchQuery};
+
+fn lex(text: &str, k: usize) -> SearchQuery {
+    SearchQuery {
+        text: text.to_string(),
+        mode: SearchMode::Lexical,
+        k,
+        filters: SearchFilters::default(),
+    }
+}
+
+#[test]
+fn search_with_opts_no_budget_matches_search() {
+    let env = common::TestEnv::new();
+    common::ingest_md(&env, "a.md", "# T\n\napples are red\n");
+    let app = env.app();
+
+    let baseline = app.search(lex("apples", 5)).unwrap();
+    let resp: SearchResponse = app
+        .search_with_opts(lex("apples", 5), SearchOpts::default())
+        .unwrap();
+
+    assert_eq!(resp.hits.len(), baseline.len());
+    assert!(!resp.truncated);
+    assert!(resp.next_cursor.is_none(), "k=5 against 1 doc → no next page");
+}
+
+#[test]
+fn budget_truncates_snippets_when_below_threshold() {
+    let env = common::TestEnv::new();
+    let body: String = "rust ownership is a memory model. ".repeat(10);
+    common::ingest_md(&env, "a.md", &format!("# T\n\n{body}\n"));
+    let app = env.app();
+
+    let unrestricted = app.search(lex("rust", 5)).unwrap();
+    let unrestricted_chars: usize = unrestricted.iter().map(|h| h.snippet.chars().count()).sum();
+
+    let resp = app
+        .search_with_opts(
+            lex("rust", 5),
+            SearchOpts {
+                max_tokens: Some(50),
+                snippet_chars: None,
+                cursor: None,
+                trace: false,
+            },
+        )
+        .unwrap();
+    let limited_chars: usize = resp.hits.iter().map(|h| h.snippet.chars().count()).sum();
+
+    assert!(resp.truncated, "small budget must trip truncation");
+    assert!(limited_chars < unrestricted_chars, "snippet should shrink");
+    assert!(!resp.hits.is_empty(), "always retain ≥1 hit");
+}
+
+#[test]
+fn cursor_paginates_to_next_page() {
+    let env = common::TestEnv::new();
+    for i in 0..6 {
+        common::ingest_md(&env, &format!("d{i}.md"), &format!("# T{i}\n\nrust topic {i}\n"));
+    }
+    let app = env.app();
+
+    let page1 = app
+        .search_with_opts(lex("rust", 2), SearchOpts::default())
+        .unwrap();
+    assert_eq!(page1.hits.len(), 2);
+    let cursor = page1.next_cursor.expect("more hits available");
+
+    let page2 = app
+        .search_with_opts(
+            lex("rust", 2),
+            SearchOpts {
+                max_tokens: None,
+                snippet_chars: None,
+                cursor: Some(cursor),
+                trace: false,
+            },
+        )
+        .unwrap();
+    assert_eq!(page2.hits.len(), 2);
+    let p1_ids: std::collections::HashSet<_> =
+        page1.hits.iter().map(|h| h.chunk_id.0.clone()).collect();
+    let p2_ids: std::collections::HashSet<_> =
+        page2.hits.iter().map(|h| h.chunk_id.0.clone()).collect();
+    assert!(p1_ids.is_disjoint(&p2_ids), "page 2 must not repeat page 1 hits");
+}
+
+#[test]
+fn cursor_rejected_after_corpus_revision_bump() {
+    let env = common::TestEnv::new();
+    common::ingest_md(&env, "a.md", "# T\n\napples\n");
+    let app = env.app();
+
+    let page1 = app
+        .search_with_opts(lex("apples", 1), SearchOpts::default())
+        .unwrap();
+    // p9-fb-34 round-1 review: replaced silent `if let Some(c) = ...`
+    // with `.expect(...)` so a fixture regression that breaks the
+    // cursor-emission contract fails loudly instead of passing vacuously.
+    let c = page1
+        .next_cursor
+        .expect("k=1 page must emit next_cursor — fixture too small if this fails");
+
+    common::ingest_md(&env, "b.md", "# B\n\nbananas\n");
+    let app2 = env.app();
+
+    let result = app2.search_with_opts(
+        lex("apples", 1),
+        SearchOpts {
+            max_tokens: None,
+            snippet_chars: None,
+            cursor: Some(c),
+            trace: false,
+        },
+    );
+    let err = result.unwrap_err();
+    assert!(
+        err.to_string().contains("stale_cursor"),
+        "must surface stale_cursor: {err}"
+    );
+}
+
+#[test]
+fn max_tokens_zero_returns_one_hit_truncated() {
+    // p9-fb-34 round-1 review: pin the documented "≥1 hit floor"
+    // contract — even with `max_tokens=0` (an absurdly tight budget)
+    // the budget loop must keep one hit and flip `truncated: true`.
+    // Fixture intentionally seeds multiple matches so step 2 of the
+    // budget loop (pop hits to 1) actually fires.
+    let env = common::TestEnv::new();
+    for i in 0..3 {
+        common::ingest_md(
+            &env,
+            &format!("d{i}.md"),
+            &format!("# T{i}\n\napples are red {i}\n"),
+        );
+    }
+    let app = env.app();
+
+    let resp = app
+        .search_with_opts(
+            lex("apples", 5),
+            SearchOpts {
+                max_tokens: Some(0),
+                snippet_chars: None,
+                cursor: None,
+                trace: false,
+            },
+        )
+        .unwrap();
+    assert_eq!(resp.hits.len(), 1, "max_tokens=0 collapses to 1-hit floor");
+    assert!(resp.truncated);
+    // p9-fb-34 R2: cursor IS emitted on k-pop case so the popped
+    // hits remain reachable.
+    assert!(
+        resp.next_cursor.is_some(),
+        "k-pop truncation must still emit next_cursor; popped hits at offset+returned"
+    );
+}

crates/kebab-app/tests/search_stale_integration.rs

@@ -0,0 +1,87 @@
+//! p9-fb-32: `App::search` end-to-end staleness wiring.
+//!
+//! `compute_stale` itself is unit-tested in `kebab_app::staleness`; this
+//! file proves the post-process actually fires through the full
+//! retriever stack and that the cache-hit re-stamp respects the
+//! configured threshold.
+//!
+//! All three tests run lexical-only (no AVX, no fastembed download).
+
+mod common;
+
+use common::TestEnv;
+
+fn lexical_query_owner() -> kebab_core::SearchQuery {
+    common::lexical_query("ownership")
+}
+
+/// Fresh ingest at default 30-day threshold → no hit can be stale.
+/// `documents.updated_at` is stamped at ingest time (now), so the
+/// distance to `now_utc()` is sub-second.
+#[test]
+fn fresh_doc_is_not_stale_with_default_threshold() {
+    let env = TestEnv::lexical_only();
+    kebab_app::ingest_with_config(env.config.clone(), env.scope(), true).unwrap();
+
+    let app = kebab_app::App::open_with_config(env.config.clone()).unwrap();
+    let hits = app.search(lexical_query_owner()).unwrap();
+    assert!(!hits.is_empty(), "expected ≥1 hit for 'ownership'");
+    assert!(
+        hits.iter().all(|h| !h.stale),
+        "freshly-ingested doc must not be stale at default 30d threshold: {:?}",
+        hits.iter().map(|h| (h.doc_path.0.clone(), h.stale)).collect::<Vec<_>>()
+    );
+}
+
+/// `stale_threshold_days = 0` disables the feature even for very old
+/// `documents.updated_at`. Backdate the row to a year ago, expect
+/// `stale: false` on every hit.
+#[test]
+fn threshold_zero_disables_staleness() {
+    let mut env = TestEnv::lexical_only();
+    env.config.search.stale_threshold_days = 0;
+
+    kebab_app::ingest_with_config(env.config.clone(), env.scope(), true).unwrap();
+    common::backdate_document_updated_at(&env, "intro.md", 365);
+
+    let app = kebab_app::App::open_with_config(env.config.clone()).unwrap();
+    let hits = app.search(lexical_query_owner()).unwrap();
+    assert!(!hits.is_empty(), "expected ≥1 hit");
+    assert!(
+        hits.iter().all(|h| !h.stale),
+        "threshold=0 disables staleness even for year-old docs: {:?}",
+        hits.iter().map(|h| (h.doc_path.0.clone(), h.stale)).collect::<Vec<_>>()
+    );
+}
+
+/// At a 30-day threshold, a 60-day-old `documents.updated_at` must
+/// surface as stale on the matching hit. (Other hits — fresh fixtures
+/// not backdated — stay fresh, so we use `any` not `all`.)
+#[test]
+fn old_doc_marked_stale() {
+    let mut env = TestEnv::lexical_only();
+    env.config.search.stale_threshold_days = 30;
+
+    kebab_app::ingest_with_config(env.config.clone(), env.scope(), true).unwrap();
+    common::backdate_document_updated_at(&env, "intro.md", 60);
+
+    let app = kebab_app::App::open_with_config(env.config.clone()).unwrap();
+    let hits = app.search(lexical_query_owner()).unwrap();
+    assert!(!hits.is_empty(), "expected ≥1 hit");
+    let intro_hits: Vec<&kebab_core::SearchHit> = hits
+        .iter()
+        .filter(|h| h.doc_path.0.ends_with("intro.md"))
+        .collect();
+    assert!(
+        !intro_hits.is_empty(),
+        "expected ≥1 hit on intro.md (the backdated doc)"
+    );
+    assert!(
+        intro_hits.iter().all(|h| h.stale),
+        "60-day-old intro.md must be stale at 30d threshold: {:?}",
+        intro_hits
+            .iter()
+            .map(|h| (h.doc_path.0.clone(), h.stale))
+            .collect::<Vec<_>>()
+    );
+}

crates/kebab-app/tests/twin_files_fetch_span.rs

@@ -0,0 +1,176 @@
+//! Regression test for the twin-file fetch_span media-type lookup bug.
+//!
+//! Twin files (identical content at different workspace paths) share one
+//! `assets` row whose PRIMARY KEY is the blake3 content hash. The old
+//! `fetch_span` implementation called
+//! `get_asset_by_workspace_path(&doc.workspace_path)` to check whether the
+//! media type was PDF/audio (and therefore reject span fetch). For a twin
+//! file that lookup could silently return the *other* twin's asset row if
+//! `assets.workspace_path` had been overwritten on the most recent ingest of
+//! the sibling — making the media-type branch decision incorrect.
+//!
+//! Fix: `fetch_span` now uses the 2-step lookup
+//!   `get_document_by_workspace_path` → `doc.source_asset_id` → `get_asset`
+//! so the result is always anchored to the requesting document, not
+//! whichever twin last updated `assets.workspace_path`.
+//!
+//! This test builds a twin-file scenario (two .md files at different paths
+//! with identical content), ingests both, then calls `fetch_span` on each
+//! twin's `doc_id` and asserts it succeeds. Before the fix, if the asset
+//! row's workspace_path happened to point at the wrong twin the span could
+//! return an incorrect `span_not_supported` for a non-PDF/audio file, or
+//! conversely allow span on a PDF twin by accident. After the fix, the
+//! lookup is always doc-specific.
+
+mod common;
+
+use common::TestEnv;
+use kebab_app::ingest_with_config;
+use kebab_core::{DocumentStore, FetchKind, FetchOpts, FetchQuery, IngestItemKind};
+
+#[test]
+fn twin_files_fetch_span_uses_correct_asset() {
+    let env = TestEnv::lexical_only();
+
+    // Write two markdown files with identical content at different paths.
+    let dir_a = env.workspace_root.join("src_a");
+    let dir_b = env.workspace_root.join("src_b");
+    std::fs::create_dir_all(&dir_a).unwrap();
+    std::fs::create_dir_all(&dir_b).unwrap();
+
+    // The content must produce at least 1 line so span fetch is non-trivial.
+    let content = "# Twin\n\nLine one.\n\nLine two.\n\nLine three.\n";
+    std::fs::write(dir_a.join("note.md"), content).unwrap();
+    std::fs::write(dir_b.join("note.md"), content).unwrap();
+
+    // Ingest all files (fixture workspace + our two new twins).
+    let report = ingest_with_config(env.config.clone(), env.scope(), false)
+        .expect("ingest must succeed");
+    assert_eq!(report.errors, 0, "no ingest errors; report={report:?}");
+
+    // Both twin paths must appear as New in the report.
+    let items = report.items.as_ref().expect("items must be present");
+    let twin_items: Vec<_> = items
+        .iter()
+        .filter(|i| {
+            i.doc_path.0.ends_with("src_a/note.md")
+                || i.doc_path.0.ends_with("src_b/note.md")
+        })
+        .collect();
+    assert_eq!(
+        twin_items.len(),
+        2,
+        "exactly 2 twin items expected; items={items:?}"
+    );
+    for item in &twin_items {
+        assert_eq!(
+            item.kind,
+            IngestItemKind::New,
+            "each twin must be New; item={item:?}"
+        );
+    }
+
+    // Resolve doc_ids for both workspace paths.
+    // The ingest layer normalises workspace_path to the path relative to
+    // workspace_root (e.g. "src_a/note.md"), so we look up by that form.
+    let store = kebab_store_sqlite::SqliteStore::open(&env.config).unwrap();
+    store.run_migrations().unwrap();
+
+    // Find the twin items by matching on suffix so the test is robust to
+    // however the workspace root is represented.
+    let items = report.items.as_ref().expect("items must be present");
+    let path_a_str = items
+        .iter()
+        .find(|i| i.doc_path.0.ends_with("src_a/note.md"))
+        .map(|i| i.doc_path.0.clone())
+        .expect("src_a/note.md must appear in ingest report");
+    let path_b_str = items
+        .iter()
+        .find(|i| i.doc_path.0.ends_with("src_b/note.md"))
+        .map(|i| i.doc_path.0.clone())
+        .expect("src_b/note.md must appear in ingest report");
+
+    let path_a = kebab_core::WorkspacePath(path_a_str);
+    let path_b = kebab_core::WorkspacePath(path_b_str);
+
+    let doc_a = store
+        .get_document_by_workspace_path(&path_a)
+        .expect("get_document_by_workspace_path path_a")
+        .expect("doc_a must exist after ingest");
+    let doc_b = store
+        .get_document_by_workspace_path(&path_b)
+        .expect("get_document_by_workspace_path path_b")
+        .expect("doc_b must exist after ingest");
+
+    // Both twins share one asset_id (same content hash).
+    assert_eq!(
+        doc_a.source_asset_id, doc_b.source_asset_id,
+        "twin files must share one asset_id"
+    );
+
+    // Open App and issue span fetch on each twin's doc_id.
+    let app = env.app();
+
+    let result_a = app
+        .fetch(
+            FetchQuery::Span {
+                doc_id: doc_a.doc_id.clone(),
+                line_start: 1,
+                line_end: 2,
+            },
+            FetchOpts::default(),
+        )
+        .expect("fetch_span on twin A must succeed for a markdown file");
+    assert_eq!(result_a.kind, FetchKind::Span);
+    assert!(
+        result_a.text.as_deref().is_some_and(|t| !t.is_empty()),
+        "span text for twin A must not be empty"
+    );
+
+    let result_b = app
+        .fetch(
+            FetchQuery::Span {
+                doc_id: doc_b.doc_id.clone(),
+                line_start: 1,
+                line_end: 2,
+            },
+            FetchOpts::default(),
+        )
+        .expect("fetch_span on twin B must succeed for a markdown file");
+    assert_eq!(result_b.kind, FetchKind::Span);
+    assert!(
+        result_b.text.as_deref().is_some_and(|t| !t.is_empty()),
+        "span text for twin B must not be empty"
+    );
+
+    // Ingest again to force the asset.workspace_path flip-flop, then
+    // re-check. Pre-fix this was the scenario that triggered the bug:
+    // after the second ingest the asset row's workspace_path could point
+    // at either twin, making one twin's span fetch behave incorrectly.
+    let report2 = ingest_with_config(env.config.clone(), env.scope(), false)
+        .expect("second ingest must succeed");
+    assert_eq!(report2.errors, 0, "no ingest errors on second run; report={report2:?}");
+
+    // Re-open app after second ingest and verify span still works on both.
+    let app2 = env.app();
+
+    app2.fetch(
+        FetchQuery::Span {
+            doc_id: doc_a.doc_id.clone(),
+            line_start: 1,
+            line_end: 3,
+        },
+        FetchOpts::default(),
+    )
+    .expect("fetch_span on twin A after flip-flop must still succeed");
+
+    app2.fetch(
+        FetchQuery::Span {
+            doc_id: doc_b.doc_id.clone(),
+            line_start: 1,
+            line_end: 3,
+        },
+        FetchOpts::default(),
+    )
+    .expect("fetch_span on twin B after flip-flop must still succeed");
+}

crates/kebab-app/tests/twin_files_idempotent.rs

@@ -0,0 +1,90 @@
+//! Regression test for the twin-file idempotency bug.
+//!
+//! Identical-content files at different workspace paths share one
+//! `assets` row (`asset_id` = blake3 content hash, PRIMARY KEY). The
+//! old UPSERT `ON CONFLICT(asset_id) DO UPDATE SET workspace_path =
+//! excluded.workspace_path` made each twin overwrite the other's path
+//! on every ingest, so `get_asset_by_workspace_path(path1)` returned
+//! None (or the wrong twin) → re-process every time.
+//!
+//! Fix: `try_skip_unchanged` now uses `get_document_by_workspace_path`
+//! instead.  `documents.workspace_path` is UNIQUE (V001) so each twin
+//! has its own stable document row.
+//!
+//! Assertion contract:
+//!   1st ingest → 2 New (one per twin)
+//!   2nd ingest → 0 New, 0 Updated, 2 Unchanged
+
+mod common;
+
+use common::TestEnv;
+use kebab_app::ingest_with_config;
+use kebab_core::IngestItemKind;
+
+#[test]
+fn twin_files_second_ingest_is_unchanged() {
+    let env = TestEnv::lexical_only();
+
+    // Write two files with identical content at different paths.
+    let pkg_a = env.workspace_root.join("pkg_a");
+    let pkg_b = env.workspace_root.join("pkg_b");
+    std::fs::create_dir_all(&pkg_a).unwrap();
+    std::fs::create_dir_all(&pkg_b).unwrap();
+
+    let content = b"# shared\nThis content is identical in both files.\n";
+    std::fs::write(pkg_a.join("__init__.py"), content).unwrap();
+    std::fs::write(pkg_b.join("__init__.py"), content).unwrap();
+
+    // First ingest — both files must be New.
+    let first = ingest_with_config(env.config.clone(), env.scope(), false)
+        .expect("first ingest must succeed");
+    assert_eq!(first.errors, 0, "first ingest: no errors; report={first:?}");
+
+    let items = first.items.as_ref().expect("items must be present");
+    let twin_items: Vec<_> = items
+        .iter()
+        .filter(|i| {
+            i.doc_path.0.ends_with("__init__.py")
+        })
+        .collect();
+    assert_eq!(
+        twin_items.len(),
+        2,
+        "first ingest: expected exactly 2 __init__.py items; items={items:?}"
+    );
+    for item in &twin_items {
+        assert_eq!(
+            item.kind,
+            IngestItemKind::New,
+            "first ingest: each twin must be New; item={item:?}"
+        );
+    }
+
+    // Second ingest — same files, same content → both must be Unchanged.
+    let second = ingest_with_config(env.config.clone(), env.scope(), false)
+        .expect("second ingest must succeed");
+    assert_eq!(second.errors, 0, "second ingest: no errors; report={second:?}");
+    assert_eq!(second.new, 0, "second ingest: no new docs; report={second:?}");
+    assert_eq!(
+        second.updated, 0,
+        "second ingest: no updated docs (twin-file bug would set this to 2); report={second:?}"
+    );
+
+    let second_items = second.items.as_ref().expect("items must be present");
+    let twin_items2: Vec<_> = second_items
+        .iter()
+        .filter(|i| i.doc_path.0.ends_with("__init__.py"))
+        .collect();
+    assert_eq!(
+        twin_items2.len(),
+        2,
+        "second ingest: expected exactly 2 __init__.py items; items={second_items:?}"
+    );
+    for item in &twin_items2 {
+        assert_eq!(
+            item.kind,
+            IngestItemKind::Unchanged,
+            "second ingest: each twin must be Unchanged; item={item:?}"
+        );
+    }
+}

crates/kebab-chunk/src/code_js_ast_v1.rs

@@ -0,0 +1,322 @@
+//! `code-js-ast-v1` — maps a tree-sitter-derived JavaScript 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-js-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 CodeJsAstV1Chunker;
+
+impl Chunker for CodeJsAstV1Chunker {
+    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!(
+                    "CodeJsAstV1Chunker only handles code docs (got non-Code block)"
+                ),
+            };
+            if !matches!(c.common.source_span, SourceSpan::Code { .. }) {
+                anyhow::bail!(
+                    "CodeJsAstV1Chunker 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-js-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.js".into());
+        let aid = AssetId("a".repeat(64));
+        let pv = ParserVersion("code-js-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("javascript".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("javascript".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("javascript".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_js_ast_v1() {
+        assert_eq!(CodeJsAstV1Chunker.chunker_version(),
+            ChunkerVersion("code-js-ast-v1".into()));
+    }
+
+    #[test]
+    fn one_chunk_per_unit_preserves_code_span() {
+        let doc = code_doc(&[
+            ("parse", 1, 3, "function parse() {\n    // x\n}"),
+            ("Foo.double", 5, 7, "function double() {\n    //\n    return 0;\n}"),
+        ]);
+        let chunks = CodeJsAstV1Chunker.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-js-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!("    const x{i} = {i};")).collect::<Vec<_>>().join("\n");
+        let code = format!("function big() {{\n{body}\n}}");
+        let doc = code_doc(&[("big", 1, 502, &code)]);
+        let chunks = CodeJsAstV1Chunker.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(); 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, "function 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 = CodeJsAstV1Chunker.chunk(&doc, &policy()).unwrap_err();
+        assert!(err.to_string().contains("CodeJsAstV1Chunker"));
+    }
+
+    #[test]
+    fn deterministic_chunk_ids_1000() {
+        let doc = code_doc(&[("parse", 1, 2, "function parse() {}\n")]);
+        let base: Vec<String> = CodeJsAstV1Chunker.chunk(&doc, &policy())
+            .unwrap().into_iter().map(|c| c.chunk_id.0).collect();
+        for _ in 0..1000 {
+            let again: Vec<String> = CodeJsAstV1Chunker.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!(CodeJsAstV1Chunker.policy_hash(&p),
+            crate::MdHeadingV1Chunker.policy_hash(&p));
+    }
+}

crates/kebab-chunk/src/code_python_ast_v1.rs

@@ -0,0 +1,322 @@
+//! `code-python-ast-v1` — maps a tree-sitter-derived Python 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-python-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 CodePythonAstV1Chunker;
+
+impl Chunker for CodePythonAstV1Chunker {
+    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!(
+                    "CodePythonAstV1Chunker only handles code docs (got non-Code block)"
+                ),
+            };
+            if !matches!(c.common.source_span, SourceSpan::Code { .. }) {
+                anyhow::bail!(
+                    "CodePythonAstV1Chunker 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-python-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.py".into());
+        let aid = AssetId("a".repeat(64));
+        let pv = ParserVersion("code-python-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("python".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("python".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("python".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_python_ast_v1() {
+        assert_eq!(CodePythonAstV1Chunker.chunker_version(),
+            ChunkerVersion("code-python-ast-v1".into()));
+    }
+
+    #[test]
+    fn one_chunk_per_unit_preserves_code_span() {
+        let doc = code_doc(&[
+            ("parse", 1, 3, "def parse():\n    pass\n    # x"),
+            ("Foo.double", 5, 7, "def double():\n    #\n    pass"),
+        ]);
+        let chunks = CodePythonAstV1Chunker.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-python-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!("    x{i} = {i}")).collect::<Vec<_>>().join("\n");
+        let code = format!("def big():\n{body}\n");
+        let doc = code_doc(&[("big", 1, 502, &code)]);
+        let chunks = CodePythonAstV1Chunker.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(); 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, "def parse(): pass")]);
+        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 = CodePythonAstV1Chunker.chunk(&doc, &policy()).unwrap_err();
+        assert!(err.to_string().contains("CodePythonAstV1Chunker"));
+    }
+
+    #[test]
+    fn deterministic_chunk_ids_1000() {
+        let doc = code_doc(&[("parse", 1, 2, "def parse(): pass\n")]);
+        let base: Vec<String> = CodePythonAstV1Chunker.chunk(&doc, &policy())
+            .unwrap().into_iter().map(|c| c.chunk_id.0).collect();
+        for _ in 0..1000 {
+            let again: Vec<String> = CodePythonAstV1Chunker.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!(CodePythonAstV1Chunker.policy_hash(&p),
+            crate::MdHeadingV1Chunker.policy_hash(&p));
+    }
+}

crates/kebab-chunk/src/code_rust_ast_v1.rs

@@ -0,0 +1,322 @@
+//! `code-rust-ast-v1` — maps a tree-sitter-derived Rust 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-rust-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 CodeRustAstV1Chunker;
+
+impl Chunker for CodeRustAstV1Chunker {
+    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!(
+                    "CodeRustAstV1Chunker only handles code docs (got non-Code block)"
+                ),
+            };
+            if !matches!(c.common.source_span, SourceSpan::Code { .. }) {
+                anyhow::bail!(
+                    "CodeRustAstV1Chunker 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-rust-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.rs".into());
+        let aid = AssetId("a".repeat(64));
+        let pv = ParserVersion("code-rust-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("rust".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("rust".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("rust".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_rust_ast_v1() {
+        assert_eq!(CodeRustAstV1Chunker.chunker_version(),
+            ChunkerVersion("code-rust-ast-v1".into()));
+    }
+
+    #[test]
+    fn one_chunk_per_unit_preserves_code_span() {
+        let doc = code_doc(&[
+            ("parse", 1, 3, "pub fn parse() {}\n// x\n}"),
+            ("Foo::double", 5, 7, "fn double() {}\n//\n}"),
+        ]);
+        let chunks = CodeRustAstV1Chunker.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-rust-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!("    let x{i} = {i};")).collect::<Vec<_>>().join("\n");
+        let code = format!("pub fn big() {{\n{body}\n}}");
+        let doc = code_doc(&[("big", 1, 502, &code)]);
+        let chunks = CodeRustAstV1Chunker.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(); 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, "fn 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 = CodeRustAstV1Chunker.chunk(&doc, &policy()).unwrap_err();
+        assert!(err.to_string().contains("CodeRustAstV1Chunker"));
+    }
+
+    #[test]
+    fn deterministic_chunk_ids_1000() {
+        let doc = code_doc(&[("parse", 1, 2, "fn parse(){}\n}")]);
+        let base: Vec<String> = CodeRustAstV1Chunker.chunk(&doc, &policy())
+            .unwrap().into_iter().map(|c| c.chunk_id.0).collect();
+        for _ in 0..1000 {
+            let again: Vec<String> = CodeRustAstV1Chunker.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!(CodeRustAstV1Chunker.policy_hash(&p),
+            crate::MdHeadingV1Chunker.policy_hash(&p));
+    }
+}

crates/kebab-chunk/src/code_ts_ast_v1.rs

@@ -0,0 +1,322 @@
+//! `code-ts-ast-v1` — maps a tree-sitter-derived TypeScript 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-ts-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 CodeTsAstV1Chunker;
+
+impl Chunker for CodeTsAstV1Chunker {
+    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!(
+                    "CodeTsAstV1Chunker only handles code docs (got non-Code block)"
+                ),
+            };
+            if !matches!(c.common.source_span, SourceSpan::Code { .. }) {
+                anyhow::bail!(
+                    "CodeTsAstV1Chunker 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-ts-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.ts".into());
+        let aid = AssetId("a".repeat(64));
+        let pv = ParserVersion("code-ts-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("typescript".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("typescript".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("typescript".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_ts_ast_v1() {
+        assert_eq!(CodeTsAstV1Chunker.chunker_version(),
+            ChunkerVersion("code-ts-ast-v1".into()));
+    }
+
+    #[test]
+    fn one_chunk_per_unit_preserves_code_span() {
+        let doc = code_doc(&[
+            ("parse", 1, 3, "function parse(): void {\n    // x\n}"),
+            ("Foo.double", 5, 7, "function double(): number {\n    //\n    return 0;\n}"),
+        ]);
+        let chunks = CodeTsAstV1Chunker.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-ts-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!("    const x{i} = {i};")).collect::<Vec<_>>().join("\n");
+        let code = format!("function big(): void {{\n{body}\n}}");
+        let doc = code_doc(&[("big", 1, 502, &code)]);
+        let chunks = CodeTsAstV1Chunker.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(); 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, "function parse(): void {}")]);
+        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 = CodeTsAstV1Chunker.chunk(&doc, &policy()).unwrap_err();
+        assert!(err.to_string().contains("CodeTsAstV1Chunker"));
+    }
+
+    #[test]
+    fn deterministic_chunk_ids_1000() {
+        let doc = code_doc(&[("parse", 1, 2, "function parse(): void {}\n")]);
+        let base: Vec<String> = CodeTsAstV1Chunker.chunk(&doc, &policy())
+            .unwrap().into_iter().map(|c| c.chunk_id.0).collect();
+        for _ in 0..1000 {
+            let again: Vec<String> = CodeTsAstV1Chunker.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!(CodeTsAstV1Chunker.policy_hash(&p),
+            crate::MdHeadingV1Chunker.policy_hash(&p));
+    }
+}

crates/kebab-chunk/src/lib.rs

@@ -15,8 +15,16 @@
 //! embedder, the retriever, the LLM, the RAG layer, or the UI layers.
 //! It consumes `CanonicalDocument` purely through `kb-core` types.
 
+mod code_js_ast_v1;
+mod code_python_ast_v1;
+mod code_rust_ast_v1;
+mod code_ts_ast_v1;
 mod md_heading_v1;
 mod pdf_page_v1;
 
+pub use code_js_ast_v1::CodeJsAstV1Chunker;
+pub use code_python_ast_v1::CodePythonAstV1Chunker;
+pub use code_rust_ast_v1::CodeRustAstV1Chunker;
+pub use code_ts_ast_v1::CodeTsAstV1Chunker;
 pub use md_heading_v1::MdHeadingV1Chunker;
 pub use pdf_page_v1::PdfPageV1Chunker;

crates/kebab-chunk/src/md_heading_v1.rs

@@ -472,6 +472,10 @@ mod tests {
                 trust_level: TrustLevel::Primary,
                 user_id_alias: None,
                 user: Default::default(),
+                repo: None,
+                git_branch: None,
+                git_commit: None,
+                code_lang: None,
             },
             provenance: Provenance { events: vec![] },
             parser_version: kebab_core::ParserVersion("test-parser-0".into()),

crates/kebab-chunk/src/pdf_page_v1.rs

@@ -347,6 +347,10 @@ mod tests {
                 trust_level: TrustLevel::Primary,
                 user_id_alias: None,
                 user: Default::default(),
+                repo: None,
+                git_branch: None,
+                git_commit: None,
+                code_lang: None,
             },
             provenance: Provenance { events: vec![] },
             parser_version,
@@ -512,6 +516,10 @@ mod tests {
                 trust_level: TrustLevel::Primary,
                 user_id_alias: None,
                 user: Default::default(),
+                repo: None,
+                git_branch: None,
+                git_commit: None,
+                code_lang: None,
             },
             provenance: Provenance { events: vec![] },
             parser_version,

crates/kebab-chunk/tests/code_js_ast_snapshot.rs

@@ -0,0 +1,221 @@
+//! Snapshot test pinning the `Vec<Chunk>` JSON for a
+//! representative JavaScript 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_rust_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::CodeJsAstV1Chunker;
+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("src/bar.js".into());
+    let aid = AssetId("b".repeat(64));
+    // Pin parser_version so doc_id / block_ids are reproducible.
+    let pv = ParserVersion("code-js-v1".into());
+    let doc_id = id_for_doc(&wp, &aid, &pv);
+
+    // Build a >200-line function body to force split_oversize.
+    let big_body: String = {
+        let header = "function bigTransform(items) {\n";
+        let body: String = (0..210u32)
+            .map(|i| format!("  const v{i} = items[{i}] !== undefined ? items[{i}] : null;\n"))
+            .collect();
+        let footer = "  return items;\n}";
+        format!("{header}{body}{footer}")
+    };
+    let big_line_count = big_body.lines().count() as u32;
+    let big_line_end = 48 + big_line_count - 1;
+
+    // Representative units:
+    //  0. require/import block       (lines 1–5,   ≤200)
+    //  1. free fn `add`              (lines 7–12,  ≤200)
+    //  2. class `EventBus`           (lines 14–20, ≤200)
+    //  3. class `BaseHandler`        (lines 22–30, ≤200)
+    //  4. method `EventBus.emit`     (lines 32–38, ≤200)
+    //  5. method `EventBus.on`       (lines 40–46, ≤200)
+    //  6. bigTransform (>200 lines)  to force split_oversize
+    let raw_units: Vec<(&str, u32, u32, String)> = vec![
+        (
+            "requires",
+            1,
+            5,
+            "const fs = require('fs');\nconst path = require('path');\nconst { EventEmitter } = require('events');\nconst assert = require('assert');\nconst crypto = require('crypto');".to_string(),
+        ),
+        (
+            "add",
+            7,
+            12,
+            "export function add(a, b) {\n  if (typeof a !== 'number') throw new TypeError('a');\n  if (typeof b !== 'number') throw new TypeError('b');\n  const result = a + b;\n  assert(isFinite(result));\n  return result;\n}".to_string(),
+        ),
+        (
+            "EventBus",
+            14,
+            20,
+            "class EventBus {\n  constructor() {\n    this._handlers = new Map();\n    this._history = [];\n    this._maxHistory = 100;\n    this._seq = 0;\n  }\n}".to_string(),
+        ),
+        (
+            "BaseHandler",
+            22,
+            30,
+            "class BaseHandler {\n  handle(event) {\n    throw new Error('not implemented');\n  }\n  batchHandle(events) {\n    const results = [];\n    for (const ev of events) {\n      results.push(this.handle(ev));\n    }\n    return results;\n  }\n}".to_string(),
+        ),
+        (
+            "EventBus.emit",
+            32,
+            38,
+            "class EventBus {\n  emit(name, payload) {\n    const handlers = this._handlers.get(name) ?? [];\n    for (const h of handlers) {\n      h(payload);\n    }\n    return this;\n  }\n}".to_string(),
+        ),
+        (
+            "EventBus.on",
+            40,
+            46,
+            "class EventBus {\n  on(name, handler) {\n    if (!this._handlers.has(name)) {\n      this._handlers.set(name, []);\n    }\n    this._handlers.get(name).push(handler);\n    return this;\n  }\n}".to_string(),
+        ),
+        ("bigTransform", 48, big_line_end, big_body),
+    ];
+
+    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("javascript".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("javascript".into()),
+                code: code.clone(),
+            })
+        })
+        .collect();
+
+    CanonicalDocument {
+        doc_id,
+        source_asset_id: aid,
+        workspace_path: wp,
+        title: "bar.js".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("javascript".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-js-ast-v1".into()),
+    }
+}
+
+#[test]
+fn code_js_ast_chunks_snapshot() {
+    let doc = fixed_doc();
+    let policy = fixed_policy();
+
+    let chunks = CodeJsAstV1Chunker.chunk(&doc, &policy).expect("chunk");
+    let actual = serde_json::to_value(&chunks).unwrap();
+
+    let dir = fixtures_dir();
+    let baseline_path = dir.join("code-sample.js.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-js-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_js_ast_chunks_are_deterministic() {
+    let policy = fixed_policy();
+    let baseline: Vec<String> = CodeJsAstV1Chunker
+        .chunk(&fixed_doc(), &policy)
+        .unwrap()
+        .into_iter()
+        .map(|c| c.chunk_id.0)
+        .collect();
+    for _ in 0..5 {
+        let again: Vec<String> = CodeJsAstV1Chunker
+            .chunk(&fixed_doc(), &policy)
+            .unwrap()
+            .into_iter()
+            .map(|c| c.chunk_id.0)
+            .collect();
+        assert_eq!(again, baseline);
+    }
+}

crates/kebab-chunk/tests/code_python_ast_snapshot.rs

@@ -0,0 +1,221 @@
+//! Snapshot test pinning the `Vec<Chunk>` JSON for a
+//! representative Python 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_rust_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::CodePythonAstV1Chunker;
+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("kebab_eval/metrics.py".into());
+    let aid = AssetId("b".repeat(64));
+    // Pin parser_version so doc_id / block_ids are reproducible.
+    let pv = ParserVersion("code-python-v1".into());
+    let doc_id = id_for_doc(&wp, &aid, &pv);
+
+    // Build a >200-line function body to force split_oversize.
+    let big_body: String = {
+        let header = "def big_compute(data):\n";
+        let body: String = (0..210u32)
+            .map(|i| format!("    v{i} = data[{i}] if {i} < len(data) else 0\n"))
+            .collect();
+        let footer = "    return sum(data)";
+        format!("{header}{body}{footer}")
+    };
+    let big_line_count = big_body.lines().count() as u32;
+    let big_line_end = 48 + big_line_count - 1;
+
+    // Representative units:
+    //  0. import block               (lines 1–5,   ≤200)
+    //  1. free fn `compute_mrr`      (lines 7–12,  ≤200)
+    //  2. class `MetricsCollector`   (lines 14–20, ≤200)
+    //  3. class `BaseEvaluator`      (lines 22–30, ≤200)
+    //  4. method `run`               (lines 32–38, ≤200)
+    //  5. method `report`            (lines 40–46, ≤200)
+    //  6. big_compute (>200 lines)   to force split_oversize
+    let raw_units: Vec<(&str, u32, u32, String)> = vec![
+        (
+            "imports",
+            1,
+            5,
+            "import os\nimport sys\nfrom typing import List\nfrom pathlib import Path\nfrom collections import defaultdict".to_string(),
+        ),
+        (
+            "compute_mrr",
+            7,
+            12,
+            "def compute_mrr(scores):\n    if not scores:\n        return 0.0\n    return sum(\n        1.0 / r for r in scores\n    ) / len(scores)".to_string(),
+        ),
+        (
+            "MetricsCollector",
+            14,
+            20,
+            "class MetricsCollector:\n    def __init__(self):\n        self.scores = []\n        self.labels = []\n        self.counts = defaultdict(int)\n        self.totals = defaultdict(float)\n        self.tags = []".to_string(),
+        ),
+        (
+            "BaseEvaluator",
+            22,
+            30,
+            "class BaseEvaluator:\n    def evaluate(self, data):\n        raise NotImplementedError\n    def batch_evaluate(self, items):\n        results = []\n        for item in items:\n            results.append(self.evaluate(item))\n        return results\n    def name(self):\n        return type(self).__name__".to_string(),
+        ),
+        (
+            "MetricsCollector.run",
+            32,
+            38,
+            "class MetricsCollector:\n    def run(self, inputs):\n        for inp in inputs:\n            score = self._score(inp)\n            self.scores.append(\n                score\n            )".to_string(),
+        ),
+        (
+            "MetricsCollector.report",
+            40,
+            46,
+            "class MetricsCollector:\n    def report(self):\n        return {\n            'mean': sum(self.scores) / max(len(self.scores), 1),\n            'count': len(self.scores),\n            'tags': self.tags,\n        }".to_string(),
+        ),
+        ("big_compute", 48, big_line_end, big_body),
+    ];
+
+    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("python".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("python".into()),
+                code: code.clone(),
+            })
+        })
+        .collect();
+
+    CanonicalDocument {
+        doc_id,
+        source_asset_id: aid,
+        workspace_path: wp,
+        title: "metrics.py".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("python".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-python-ast-v1".into()),
+    }
+}
+
+#[test]
+fn code_python_ast_chunks_snapshot() {
+    let doc = fixed_doc();
+    let policy = fixed_policy();
+
+    let chunks = CodePythonAstV1Chunker.chunk(&doc, &policy).expect("chunk");
+    let actual = serde_json::to_value(&chunks).unwrap();
+
+    let dir = fixtures_dir();
+    let baseline_path = dir.join("code-sample.py.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-python-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_python_ast_chunks_are_deterministic() {
+    let policy = fixed_policy();
+    let baseline: Vec<String> = CodePythonAstV1Chunker
+        .chunk(&fixed_doc(), &policy)
+        .unwrap()
+        .into_iter()
+        .map(|c| c.chunk_id.0)
+        .collect();
+    for _ in 0..5 {
+        let again: Vec<String> = CodePythonAstV1Chunker
+            .chunk(&fixed_doc(), &policy)
+            .unwrap()
+            .into_iter()
+            .map(|c| c.chunk_id.0)
+            .collect();
+        assert_eq!(again, baseline);
+    }
+}

crates/kebab-chunk/tests/code_rust_ast_snapshot.rs

@@ -0,0 +1,221 @@
+//! Snapshot test pinning the `Vec<Chunk>` JSON for a
+//! representative Rust 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_rust_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::CodeRustAstV1Chunker;
+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("crates/kebab-chunk/src/code_rust_ast_v1.rs".into());
+    let aid = AssetId("b".repeat(64));
+    // Pin parser_version so doc_id / block_ids are reproducible.
+    let pv = ParserVersion("code-rust-v1".into());
+    let doc_id = id_for_doc(&wp, &aid, &pv);
+
+    // Build a >200-line function body to force split_oversize.
+    let big_body: String = {
+        let header = "pub fn big_fn(input: &[u8]) -> Vec<u8> {\n";
+        let body: String = (0..210u32)
+            .map(|i| format!("    let v{i} = input.get({i} as usize).copied().unwrap_or(0);\n"))
+            .collect();
+        let footer = "    vec![0u8]\n}";
+        format!("{header}{body}{footer}")
+    };
+    let big_line_count = big_body.lines().count() as u32;
+    let big_line_end = 48 + big_line_count - 1;
+
+    // Representative units:
+    //  0. top-level use+const block  (lines 1–5,   ≤200)
+    //  1. free fn `parse`            (lines 7–12,  ≤200)
+    //  2. struct `Foo`               (lines 14–20, ≤200)
+    //  3. trait `Frobable`           (lines 22–30, ≤200)
+    //  4. impl Foo::double           (lines 32–38, ≤200)
+    //  5. impl Foo::triple           (lines 40–46, ≤200)
+    //  6. big_fn (>200 lines)        to force split_oversize
+    let raw_units: Vec<(&str, u32, u32, String)> = vec![
+        (
+            "use+const",
+            1,
+            5,
+            "use std::collections::HashMap;\nuse std::fmt;\n\nconst MAX: usize = 1024;\nconst MIN: usize = 0;".to_string(),
+        ),
+        (
+            "parse",
+            7,
+            12,
+            "pub fn parse(input: &str) -> Option<u32> {\n    input\n        .trim()\n        .parse()\n        .ok()\n}".to_string(),
+        ),
+        (
+            "Foo",
+            14,
+            20,
+            "pub struct Foo {\n    pub name: String,\n    pub value: u32,\n    pub tags: Vec<String>,\n    pub meta: Option<String>,\n    pub count: usize,\n}".to_string(),
+        ),
+        (
+            "Frobable",
+            22,
+            30,
+            "pub trait Frobable {\n    fn frob(&self) -> String;\n    fn frob_twice(&self) -> String {\n        let a = self.frob();\n        let b = self.frob();\n        format!(\"{a}{b}\")\n    }\n    fn name(&self) -> &str;\n}".to_string(),
+        ),
+        (
+            "Foo::double",
+            32,
+            38,
+            "impl Foo {\n    pub fn double(&self) -> u32 {\n        self.value\n            .checked_mul(2)\n            .unwrap_or(u32::MAX)\n    }\n}".to_string(),
+        ),
+        (
+            "Foo::triple",
+            40,
+            46,
+            "impl Foo {\n    pub fn triple(&self) -> u32 {\n        self.value\n            .checked_mul(3)\n            .unwrap_or(u32::MAX)\n    }\n}".to_string(),
+        ),
+        ("big_fn", 48, big_line_end, big_body),
+    ];
+
+    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("rust".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("rust".into()),
+                code: code.clone(),
+            })
+        })
+        .collect();
+
+    CanonicalDocument {
+        doc_id,
+        source_asset_id: aid,
+        workspace_path: wp,
+        title: "code_rust_ast_v1.rs".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("rust".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-rust-ast-v1".into()),
+    }
+}
+
+#[test]
+fn code_rust_ast_chunks_snapshot() {
+    let doc = fixed_doc();
+    let policy = fixed_policy();
+
+    let chunks = CodeRustAstV1Chunker.chunk(&doc, &policy).expect("chunk");
+    let actual = serde_json::to_value(&chunks).unwrap();
+
+    let dir = fixtures_dir();
+    let baseline_path = dir.join("code-sample.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-rust-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_rust_ast_chunks_are_deterministic() {
+    let policy = fixed_policy();
+    let baseline: Vec<String> = CodeRustAstV1Chunker
+        .chunk(&fixed_doc(), &policy)
+        .unwrap()
+        .into_iter()
+        .map(|c| c.chunk_id.0)
+        .collect();
+    for _ in 0..5 {
+        let again: Vec<String> = CodeRustAstV1Chunker
+            .chunk(&fixed_doc(), &policy)
+            .unwrap()
+            .into_iter()
+            .map(|c| c.chunk_id.0)
+            .collect();
+        assert_eq!(again, baseline);
+    }
+}

crates/kebab-chunk/tests/code_ts_ast_snapshot.rs

@@ -0,0 +1,221 @@
+//! Snapshot test pinning the `Vec<Chunk>` JSON for a
+//! representative TypeScript 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_rust_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::CodeTsAstV1Chunker;
+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("src/Foo.ts".into());
+    let aid = AssetId("b".repeat(64));
+    // Pin parser_version so doc_id / block_ids are reproducible.
+    let pv = ParserVersion("code-ts-v1".into());
+    let doc_id = id_for_doc(&wp, &aid, &pv);
+
+    // Build a >200-line method body to force split_oversize.
+    let big_body: String = {
+        let header = "export class BigProcessor {\n  process(items: string[]): string[] {\n";
+        let body: String = (0..210u32)
+            .map(|i| format!("    const v{i} = items[{i}] ?? '';\n"))
+            .collect();
+        let footer = "    return items;\n  }\n}";
+        format!("{header}{body}{footer}")
+    };
+    let big_line_count = big_body.lines().count() as u32;
+    let big_line_end = 48 + big_line_count - 1;
+
+    // Representative units:
+    //  0. import block               (lines 1–5,   ≤200)
+    //  1. free fn `parseInput`       (lines 7–12,  ≤200)
+    //  2. interface `Frobable`       (lines 14–20, ≤200)
+    //  3. class `Foo`                (lines 22–30, ≤200)
+    //  4. method `Foo.double`        (lines 32–38, ≤200)
+    //  5. method `Foo.triple`        (lines 40–46, ≤200)
+    //  6. BigProcessor (>200 lines)  to force split_oversize
+    let raw_units: Vec<(&str, u32, u32, String)> = vec![
+        (
+            "imports",
+            1,
+            5,
+            "import { readFileSync } from 'fs';\nimport { join } from 'path';\nimport type { Config } from './config';\nimport { Logger } from './logger';\nimport { EventEmitter } from 'events';".to_string(),
+        ),
+        (
+            "parseInput",
+            7,
+            12,
+            "export function parseInput(raw: string): number | null {\n  const trimmed = raw.trim();\n  const n = Number(trimmed);\n  if (isNaN(n)) return null;\n  return n;\n}".to_string(),
+        ),
+        (
+            "Frobable",
+            14,
+            20,
+            "export interface Frobable {\n  frob(): string;\n  frobTwice(): string;\n  readonly name: string;\n  readonly tags: string[];\n  count: number;\n  reset(): void;\n}".to_string(),
+        ),
+        (
+            "Foo",
+            22,
+            30,
+            "export class Foo implements Frobable {\n  constructor(\n    public readonly name: string,\n    public value: number,\n    public tags: string[] = [],\n  ) {}\n  frob(): string { return this.name; }\n  frobTwice(): string { return this.name.repeat(2); }\n  reset(): void { this.value = 0; }\n}".to_string(),
+        ),
+        (
+            "Foo.double",
+            32,
+            38,
+            "export class Foo {\n  double(): number {\n    const result = this.value * 2;\n    if (result > Number.MAX_SAFE_INTEGER) {\n      return Number.MAX_SAFE_INTEGER;\n    }\n    return result;\n  }\n}".to_string(),
+        ),
+        (
+            "Foo.triple",
+            40,
+            46,
+            "export class Foo {\n  triple(): number {\n    const result = this.value * 3;\n    if (result > Number.MAX_SAFE_INTEGER) {\n      return Number.MAX_SAFE_INTEGER;\n    }\n    return result;\n  }\n}".to_string(),
+        ),
+        ("BigProcessor", 48, big_line_end, big_body),
+    ];
+
+    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("typescript".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("typescript".into()),
+                code: code.clone(),
+            })
+        })
+        .collect();
+
+    CanonicalDocument {
+        doc_id,
+        source_asset_id: aid,
+        workspace_path: wp,
+        title: "Foo.ts".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("typescript".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-ts-ast-v1".into()),
+    }
+}
+
+#[test]
+fn code_ts_ast_chunks_snapshot() {
+    let doc = fixed_doc();
+    let policy = fixed_policy();
+
+    let chunks = CodeTsAstV1Chunker.chunk(&doc, &policy).expect("chunk");
+    let actual = serde_json::to_value(&chunks).unwrap();
+
+    let dir = fixtures_dir();
+    let baseline_path = dir.join("code-sample.ts.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-ts-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_ts_ast_chunks_are_deterministic() {
+    let policy = fixed_policy();
+    let baseline: Vec<String> = CodeTsAstV1Chunker
+        .chunk(&fixed_doc(), &policy)
+        .unwrap()
+        .into_iter()
+        .map(|c| c.chunk_id.0)
+        .collect();
+    for _ in 0..5 {
+        let again: Vec<String> = CodeTsAstV1Chunker
+            .chunk(&fixed_doc(), &policy)
+            .unwrap()
+            .into_iter()
+            .map(|c| c.chunk_id.0)
+            .collect();
+        assert_eq!(again, baseline);
+    }
+}

crates/kebab-cli/Cargo.toml

@@ -27,10 +27,12 @@ kebab-eval = { path = "../kebab-eval" }
 # enforces the §8 boundary in its own Cargo.toml; kb-cli just
 # launches it.
 kebab-tui    = { path = "../kebab-tui" }
+# p9-fb-30: MCP stdio server. `Cmd::Mcp` delegates entirely to this crate.
+kebab-mcp    = { path = "../kebab-mcp" }
 anyhow       = { workspace = true }
 serde        = { workspace = true }
 serde_json   = { workspace = true }
-clap         = { version = "4", features = ["derive"] }
+clap         = { version = "4", features = ["derive", "env"] }
 # p9-fb-02: ingest progress UI.
 # - TTY 사람 모드: indicatif spinner + bar (stderr).
 # - --json 모드 / non-TTY: indicatif 끄고 raw line emit.
@@ -44,6 +46,7 @@ ctrlc        = "3"
 
 [dev-dependencies]
 tempfile     = { workspace = true }
-# llm_unreachable_classifies_to_model_unreachable test needs a real
-# reqwest::Error (private constructor) — built from a connect-refused call.
-reqwest      = { version = "0.12", default-features = false, features = ["blocking", "rustls-tls"] }
+# p9-fb-32: backdate `documents.updated_at` in CLI integration tests
+# to simulate stale docs. `time` is the formatter used by the helper.
+rusqlite     = { workspace = true }
+time         = { workspace = true }

crates/kebab-cli/src/progress.rs

@@ -39,18 +39,22 @@ pub enum ProgressMode {
     Json,
     /// stdout reserved for the final report; stderr gets an indicatif
     /// `ProgressBar` (TTY) or one short line per event (non-TTY).
-    Human { tty: bool },
+    Human { tty: bool, quiet: bool },
 }
 
 impl ProgressMode {
     /// Pick the right mode from caller flags.
-    pub fn from_flags(json: bool) -> Self {
+    ///
+    /// - `json`: `--json` flag — takes priority, returns `Json`.
+    /// - `quiet`: `--quiet` flag — suppresses human-readable stderr when `Human`.
+    /// - `plain_env`: `KEBAB_PROGRESS=plain` — forces `tty=false` even in a TTY,
+    ///   for CI environments that emulate a TTY with a pty wrapper.
+    pub fn from_flags(json: bool, quiet: bool, plain_env: bool) -> Self {
         if json {
             Self::Json
         } else {
-            Self::Human {
-                tty: std::io::stderr().is_terminal(),
-            }
+            let tty = !plain_env && std::io::stderr().is_terminal();
+            Self::Human { tty, quiet }
         }
     }
 }
@@ -83,7 +87,7 @@ impl ProgressDisplay {
     fn handle(&mut self, event: &IngestEvent) -> anyhow::Result<()> {
         match self.mode {
             ProgressMode::Json => emit_json(event),
-            ProgressMode::Human { tty } => self.handle_human(event, tty),
+            ProgressMode::Human { tty, quiet } => self.handle_human(event, tty, quiet),
         }
     }
 
@@ -96,18 +100,20 @@ impl ProgressDisplay {
     /// `ScanStarted` arm and §2.4a's ordering invariant
     /// (`ScanStarted` < everything else) guarantees it is `Some` by
     /// the time later events arrive.
-    fn handle_human(&mut self, event: &IngestEvent, tty: bool) -> anyhow::Result<()> {
+    fn handle_human(&mut self, event: &IngestEvent, tty: bool, quiet: bool) -> anyhow::Result<()> {
         match event {
             IngestEvent::ScanStarted { root } => {
                 let bar = ProgressBar::new_spinner().with_message(format!("scanning {root}"));
-                bar.set_draw_target(if tty {
+                bar.set_draw_target(if tty && !quiet {
                     ProgressDrawTarget::stderr()
                 } else {
                     ProgressDrawTarget::hidden()
                 });
-                bar.enable_steady_tick(std::time::Duration::from_millis(100));
+                if tty && !quiet {
+                    bar.enable_steady_tick(std::time::Duration::from_millis(100));
+                }
                 self.bar = Some(bar);
-                if !tty {
+                if !tty && !quiet {
                     let mut err = std::io::stderr().lock();
                     let _ = writeln!(err, "ingest: scanning {root}…");
                 }
@@ -126,7 +132,7 @@ impl ProgressDisplay {
                     );
                     bar.set_message("");
                 }
-                if !tty {
+                if !tty && !quiet {
                     let mut err = std::io::stderr().lock();
                     let _ = writeln!(err, "ingest: scan complete ({total} assets)");
                 }
@@ -138,23 +144,28 @@ impl ProgressDisplay {
                 media,
             } => {
                 if let Some(bar) = self.bar.as_ref() {
-                    bar.set_message(format!("{media} {path}"));
+                    // One draw per file: position only. set_message() would
+                    // trigger a second independent draw and pollute TTY scrollback.
+                    // Filename is visible in the non-TTY plain-line path below.
+                    bar.set_position(u64::from(idx.saturating_sub(1)));
                 }
-                if !tty {
+                if !tty && !quiet {
                     let mut err = std::io::stderr().lock();
                     let _ = writeln!(err, "ingest: {idx}/{total} {media} {path}");
                 }
             }
-            IngestEvent::AssetFinished { idx, .. } => {
-                if let Some(bar) = self.bar.as_ref() {
-                    bar.set_position(u64::from(*idx));
-                }
+            IngestEvent::AssetFinished { .. } => {
+                // Position is advanced in AssetStarted; bar.finish_and_clear()
+                // in Completed handles the final state. No per-asset bar update
+                // here avoids the duplicate-frame artifact in TTY scrollback.
             }
             IngestEvent::Completed { counts } => {
                 if let Some(bar) = self.bar.take() {
                     bar.finish_and_clear();
                 }
-                if !tty {
+                // Always emit summary in both TTY and non-TTY (unless quiet).
+                // Bug fix: previously TTY had no summary line after bar.finish_and_clear().
+                if !quiet {
                     let mut err = std::io::stderr().lock();
                     let _ = writeln!(
                         err,
@@ -175,16 +186,20 @@ impl ProgressDisplay {
                         counts.scanned
                     ));
                 }
-                let mut err = std::io::stderr().lock();
-                let _ = writeln!(
-                    err,
-                    "ingest: aborted (scanned={} new={} updated={} skipped={} errors={})",
-                    counts.scanned,
-                    counts.new,
-                    counts.updated,
-                    counts.skipped,
-                    counts.errors,
-                );
+                // Bug fix: was unconditional (fired in TTY too).
+                // In TTY, bar.abandon_with_message already prints the final state.
+                if !tty && !quiet {
+                    let mut err = std::io::stderr().lock();
+                    let _ = writeln!(
+                        err,
+                        "ingest: aborted (scanned={} new={} updated={} skipped={} errors={})",
+                        counts.scanned,
+                        counts.new,
+                        counts.updated,
+                        counts.skipped,
+                        counts.errors,
+                    );
+                }
             }
         }
         Ok(())
@@ -216,20 +231,35 @@ mod tests {
 
     #[test]
     fn from_flags_json_takes_priority_over_tty() {
-        // --json forces Json regardless of TTY state.
-        assert_eq!(ProgressMode::from_flags(true), ProgressMode::Json);
+        assert_eq!(ProgressMode::from_flags(true, false, false), ProgressMode::Json);
     }
 
     #[test]
     fn from_flags_human_reflects_stderr_tty() {
         // We can't synthesize a TTY in tests, but we can assert the
         // shape — mode is Human { tty: <something> } when --json=false.
-        match ProgressMode::from_flags(false) {
+        match ProgressMode::from_flags(false, false, false) {
             ProgressMode::Human { .. } => {}
             other => panic!("expected Human mode, got {other:?}"),
         }
     }
 
+    #[test]
+    fn from_flags_quiet_sets_quiet_field() {
+        match ProgressMode::from_flags(false, true, false) {
+            ProgressMode::Human { quiet: true, .. } => {}
+            other => panic!("expected Human{{quiet:true}}, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn from_flags_plain_env_forces_tty_false() {
+        match ProgressMode::from_flags(false, false, true) {
+            ProgressMode::Human { tty: false, .. } => {}
+            other => panic!("expected Human{{tty:false}}, got {other:?}"),
+        }
+    }
+
     #[test]
     fn now_rfc3339_parses_back() {
         let s = now_rfc3339().unwrap();

crates/kebab-cli/src/wire.rs

@@ -75,10 +75,24 @@ pub fn wire_search_hit(h: &SearchHit) -> Value {
     tag_object(v, "search_hit.v1")
 }
 
-/// Wrap a list of [`SearchHit`] values as a JSON array of `search_hit.v1`
-/// objects (one tag per element, per design §2.2).
-pub fn wire_search_hits(hits: &[SearchHit]) -> Value {
-    Value::Array(hits.iter().map(wire_search_hit).collect())
+/// p9-fb-34: tag a `SearchResponse` as `search_response.v1`. Wraps
+/// the existing `search_hit.v1[]` array with pagination + truncation
+/// metadata. Replaces the previous bare `search_hit.v1[]` top-level
+/// array (`wire_search_hits`) — see HOTFIXES / fb-34 for the
+/// breaking shape change.
+pub fn wire_search_response(r: &kebab_app::SearchResponse) -> Value {
+    let mut v = serde_json::json!({
+        "hits": r.hits.iter().map(wire_search_hit).collect::<Vec<_>>(),
+        "next_cursor": r.next_cursor,
+        "truncated": r.truncated,
+    });
+    if let Some(trace) = &r.trace {
+        let trace_v = serde_json::to_value(trace).expect("SearchTrace serializes");
+        if let Value::Object(ref mut map) = v {
+            map.insert("trace".to_string(), trace_v);
+        }
+    }
+    tag_object(v, "search_response.v1")
 }
 
 /// Wrap an [`Answer`] as `answer.v1`.
@@ -87,6 +101,25 @@ pub fn wire_answer(a: &Answer) -> Value {
     tag_object(v, "answer.v1")
 }
 
+/// p9-fb-33: tag a [`StreamEvent`] as `answer_event.v1` ndjson.
+///
+/// The timestamp is added at emit time (caller fills `ts`), since the
+/// pipeline doesn't carry one in the in-process enum — mirrors the
+/// `wire_ingest_progress` pattern (§2 ingest_progress.v1).
+pub fn wire_answer_event(
+    ev: &kebab_app::StreamEvent,
+    ts: time::OffsetDateTime,
+) -> Value {
+    let mut v = serde_json::to_value(ev).expect("StreamEvent serializes");
+    let ts_str = ts
+        .format(&time::format_description::well_known::Rfc3339)
+        .expect("OffsetDateTime formats as RFC3339");
+    if let Value::Object(ref mut map) = v {
+        map.insert("ts".to_string(), Value::String(ts_str));
+    }
+    tag_object(v, "answer_event.v1")
+}
+
 /// Idempotent pass-through for [`DoctorReport`] — the type already carries
 /// `schema_version: "doctor.v1"` (struct-field convention, the one
 /// exception called out in the module doc above). This helper exists so
@@ -152,16 +185,36 @@ pub fn wire_schema(s: &kebab_app::SchemaV1) -> Value {
     tag_object(v, kebab_app::SCHEMA_V1_ID)
 }
 
-/// Wrap an [`crate::error_classify::ErrorV1`] as `error.v1`.
+/// Wrap an [`kebab_app::ErrorV1`] as `error.v1`.
 ///
 /// Uses the simple `tag_object` pattern because `ErrorV1` is a
-/// kebab-cli-local type that does NOT carry `schema_version` itself
+/// type that does NOT carry `schema_version` itself
 /// (kebab-core convention).
-pub fn wire_error_v1(e: &crate::error_classify::ErrorV1) -> Value {
+pub fn wire_error_v1(e: &kebab_app::ErrorV1) -> Value {
     let v = serde_json::to_value(e).expect("ErrorV1 serializes");
     tag_object(v, "error.v1")
 }
 
+/// p9-fb-35: tag a [`kebab_core::FetchResult`] as `fetch_result.v1`.
+pub fn wire_fetch_result(r: &kebab_core::FetchResult) -> Value {
+    let v = serde_json::to_value(r).expect("FetchResult serializes");
+    tag_object(v, "fetch_result.v1")
+}
+
+/// p9-fb-42: tag a `BulkSearchItem` (already serialized as a Value)
+/// as `bulk_search_item.v1`. The inner `query` / `response` / `error`
+/// fields stay verbatim — only the envelope gets the schema_version stamp.
+pub fn wire_bulk_search_item(item: &kebab_core::BulkSearchItem) -> Value {
+    let mut v = serde_json::to_value(item).expect("BulkSearchItem serializes");
+    if let Value::Object(ref mut map) = v {
+        map.insert(
+            "schema_version".to_string(),
+            Value::String("bulk_search_item.v1".to_string()),
+        );
+    }
+    v
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -186,7 +239,7 @@ mod tests {
 
     #[test]
     fn ingest_wrapper_tags_schema_version() {
-        use kebab_core::SourceScope;
+        use kebab_core::{SkipExamples, SourceScope};
         let r = IngestReport {
             scope: SourceScope {
                 root: std::path::PathBuf::from("/tmp"),
@@ -201,6 +254,13 @@ mod tests {
             errors: 0,
             duration_ms: 0,
             skipped_by_extension: std::collections::BTreeMap::new(),
+            skipped_gitignore: 0,
+            skipped_kebabignore: 0,
+            skipped_builtin_blacklist: 0,
+            skipped_generated: 0,
+            skipped_size_exceeded: 0,
+            skip_examples: SkipExamples::default(),
+            purged_deleted_files: 0,
             items: None,
         };
         let v = wire_ingest(&r);
@@ -215,13 +275,6 @@ mod tests {
         assert_eq!(v.as_array().unwrap().len(), 0);
     }
 
-    #[test]
-    fn search_hits_wraps_each_element() {
-        let v = wire_search_hits(&[]);
-        assert!(v.is_array());
-        assert_eq!(v.as_array().unwrap().len(), 0);
-    }
-
     #[test]
     fn tag_object_inserts_into_object() {
         let v = Value::Object(serde_json::Map::new());
@@ -229,6 +282,31 @@ mod tests {
         assert_eq!(schema_of(&tagged), Some("x.v1"));
     }
 
+    #[test]
+    fn search_response_carries_pagination_metadata() {
+        // p9-fb-34: empty-hits SearchResponse round-trips through the
+        // wrapper with its `next_cursor` + `truncated` fields preserved
+        // and the top-level `schema_version` set to `search_response.v1`.
+        let r = kebab_app::SearchResponse {
+            hits: vec![],
+            next_cursor: Some("opaque-cursor-abc".to_string()),
+            truncated: true,
+            trace: None,
+        };
+        let v = wire_search_response(&r);
+        assert_eq!(schema_of(&v), Some("search_response.v1"));
+        assert!(v.get("hits").and_then(|h| h.as_array()).is_some());
+        assert_eq!(
+            v.get("hits").and_then(|h| h.as_array()).unwrap().len(),
+            0
+        );
+        assert_eq!(
+            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));
+    }
+
     #[test]
     fn schema_wrapper_tags_schema_version() {
         use kebab_app::{Capabilities, Models, SchemaV1, Stats, WireBlock};
@@ -240,7 +318,7 @@ mod tests {
                 json_mode: true, ingest_progress: true, ingest_cancellation: true,
                 rag_multi_turn: true, search_cache: true, incremental_ingest: true,
                 streaming_ask: false, http_daemon: false, mcp_server: false,
-                single_file_ingest: false,
+                single_file_ingest: false, bulk_search: true,
             },
             models: Models {
                 parser_version: "x".to_string(),
@@ -253,6 +331,12 @@ mod tests {
             stats: Stats {
                 doc_count: 1, chunk_count: 2, asset_count: 1,
                 last_ingest_at: None,
+                media_breakdown: Default::default(),
+                lang_breakdown: Default::default(),
+                index_bytes: Default::default(),
+                stale_doc_count: 0,
+                // p10-1A-1: new fields added to Stats; use Default for the test fixture.
+                ..Default::default()
             },
         };
         let v = wire_schema(&schema);
@@ -262,8 +346,9 @@ mod tests {
 
     #[test]
     fn error_wrapper_tags_schema_version_and_emits_code() {
-        use crate::error_classify::ErrorV1;
+        use kebab_app::ErrorV1;
         let err = ErrorV1 {
+            schema_version: "error.v1".to_string(),
             code: "config_invalid".to_string(),
             message: "bad config".to_string(),
             details: serde_json::json!({"path": "/tmp/x"}),
@@ -280,6 +365,8 @@ mod tests {
             scope: kebab_app::ResetScope::DataOnly,
             removed_paths: vec![std::path::PathBuf::from("/tmp/x")],
             embedding_rows_truncated: 0,
+            orphans_purged: 0,
+            purged_paths: vec![],
         };
         let v = wire_reset(&r);
         assert_eq!(schema_of(&v), Some("reset_report.v1"));
@@ -292,4 +379,49 @@ mod tests {
         assert_eq!(paths.len(), 1);
         assert_eq!(paths[0].as_str(), Some("/tmp/x"));
     }
+
+    #[test]
+    fn search_response_with_trace_serializes_trace_field() {
+        use kebab_core::{SearchTrace, TraceCandidate, TraceFusionInput,
+                         TraceTiming, ChunkId, DocumentId, WorkspacePath};
+        let r = kebab_app::SearchResponse {
+            hits: vec![],
+            next_cursor: None,
+            truncated: false,
+            trace: Some(SearchTrace {
+                lexical: vec![TraceCandidate {
+                    chunk_id: ChunkId("c1".into()),
+                    doc_id: DocumentId("d1".into()),
+                    doc_path: WorkspacePath::new("a.md".into()).unwrap(),
+                    rank: 1,
+                    score: 0.42,
+                }],
+                vector: vec![],
+                rrf_inputs: vec![TraceFusionInput {
+                    chunk_id: ChunkId("c1".into()),
+                    lexical_rank: Some(1),
+                    vector_rank: None,
+                    fusion_score: 0.0,
+                }],
+                timing: TraceTiming { lexical_ms: 5, vector_ms: 0, fusion_ms: 1, total_ms: 7 },
+            }),
+        };
+        let v = wire_search_response(&r);
+        assert_eq!(schema_of(&v), Some("search_response.v1"));
+        assert!(v["trace"].is_object());
+        assert_eq!(v["trace"]["timing"]["lexical_ms"], 5);
+        assert_eq!(v["trace"]["lexical"][0]["chunk_id"], "c1");
+    }
+
+    #[test]
+    fn search_response_without_trace_omits_field() {
+        let r = kebab_app::SearchResponse {
+            hits: vec![],
+            next_cursor: None,
+            truncated: false,
+            trace: 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

@@ -0,0 +1,92 @@
+//! Integration: spawn `kebab ingest-file <path>` and verify ingest_report.v1.
+
+use std::fs;
+use std::process::Command;
+
+#[test]
+fn cli_ingest_file_emits_ingest_report_v1() {
+    let dir = tempfile::tempdir().unwrap();
+    let workspace = dir.path().join("notes");
+    let data = dir.path().join("data");
+    fs::create_dir_all(&workspace).unwrap();
+    fs::create_dir_all(&data).unwrap();
+
+    let cfg_path = dir.path().join("config.toml");
+    fs::write(
+        &cfg_path,
+        format!(
+            r#"schema_version = 1
+
+[workspace]
+root = "{workspace}"
+exclude = [".git/**"]
+
+[storage]
+data_dir = "{data}"
+sqlite = "{{data_dir}}/kebab.sqlite"
+vector_dir = "{{data_dir}}/lancedb"
+asset_dir = "{{data_dir}}/assets"
+artifact_dir = "{{data_dir}}/artifacts"
+model_dir = "{{data_dir}}/models"
+runs_dir = "{{data_dir}}/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 = "none"
+model = "none"
+version = "v0"
+dimensions = 0
+batch_size = 1
+
+[models.llm]
+provider = "ollama"
+model = "none"
+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-v1"
+score_gate = 0.30
+explain_default = false
+max_context_tokens = 8000
+"#,
+            workspace = workspace.display(),
+            data = data.display(),
+        ),
+    ).unwrap();
+
+    let src = dir.path().join("doc.md");
+    fs::write(&src, "# A\n\nbody.").unwrap();
+
+    let bin = env!("CARGO_BIN_EXE_kebab");
+    let out = Command::new(bin)
+        .args(["--json", "--config", cfg_path.to_str().unwrap(), "ingest-file"])
+        .arg(&src)
+        .output()
+        .unwrap();
+    assert!(out.status.success(), "stderr: {}", String::from_utf8_lossy(&out.stderr));
+
+    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));
+}

crates/kebab-cli/tests/cli_ingest_stdin.rs

@@ -0,0 +1,100 @@
+//! Integration: spawn `kebab ingest-stdin --title X` with stdin pipe.
+
+use std::fs;
+use std::io::Write;
+use std::process::{Command, Stdio};
+
+#[test]
+fn cli_ingest_stdin_emits_ingest_report_v1() {
+    let dir = tempfile::tempdir().unwrap();
+    let workspace = dir.path().join("notes");
+    let data = dir.path().join("data");
+    fs::create_dir_all(&workspace).unwrap();
+    fs::create_dir_all(&data).unwrap();
+
+    let cfg_path = dir.path().join("config.toml");
+    fs::write(
+        &cfg_path,
+        format!(
+            r#"schema_version = 1
+
+[workspace]
+root = "{workspace}"
+exclude = [".git/**"]
+
+[storage]
+data_dir = "{data}"
+sqlite = "{{data_dir}}/kebab.sqlite"
+vector_dir = "{{data_dir}}/lancedb"
+asset_dir = "{{data_dir}}/assets"
+artifact_dir = "{{data_dir}}/artifacts"
+model_dir = "{{data_dir}}/models"
+runs_dir = "{{data_dir}}/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 = "none"
+model = "none"
+version = "v0"
+dimensions = 0
+batch_size = 1
+
+[models.llm]
+provider = "ollama"
+model = "none"
+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-v1"
+score_gate = 0.30
+explain_default = false
+max_context_tokens = 8000
+"#,
+            workspace = workspace.display(),
+            data = data.display(),
+        ),
+    ).unwrap();
+
+    let bin = env!("CARGO_BIN_EXE_kebab");
+    let mut child = Command::new(bin)
+        .args([
+            "--json", "--config", cfg_path.to_str().unwrap(),
+            "ingest-stdin", "--title", "X",
+        ])
+        .stdin(Stdio::piped())
+        .stdout(Stdio::piped())
+        .stderr(Stdio::piped())
+        .spawn()
+        .unwrap();
+    {
+        let stdin = child.stdin.as_mut().unwrap();
+        stdin.write_all(b"## Body\n\nbody text.\n").unwrap();
+    }
+    let out = child.wait_with_output().unwrap();
+    assert!(out.status.success(), "stderr: {}", String::from_utf8_lossy(&out.stderr));
+
+    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));
+}

crates/kebab-cli/tests/cli_mcp_smoke.rs

@@ -0,0 +1,77 @@
+//! Spawn `target/debug/kebab mcp` and exercise initialize → tools/list.
+//!
+//! rmcp 1.6 has no public in-memory test transport, so this is the only
+//! end-to-end MCP assertion in the suite. The binary is located via
+//! `CARGO_BIN_EXE_kebab` which cargo injects at test compile time.
+
+use std::io::{BufRead, BufReader, Write};
+use std::process::{Command, Stdio};
+
+#[test]
+fn cli_mcp_initialize_then_tools_list() {
+    let bin = env!("CARGO_BIN_EXE_kebab");
+    let mut child = Command::new(bin)
+        .arg("mcp")
+        .stdin(Stdio::piped())
+        .stdout(Stdio::piped())
+        .stderr(Stdio::null())
+        .spawn()
+        .unwrap();
+
+    let mut stdin = child.stdin.take().unwrap();
+    let stdout = child.stdout.take().unwrap();
+    let mut reader = BufReader::new(stdout);
+
+    // rmcp 1.6 defaults to protocol version "2025-03-26" (confirmed by
+    // manual smoke in Task 10). The server echoes whatever version the
+    // client sends during the handshake, so this literal must match.
+    let init_req = r#"{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"0"}}}"#;
+    writeln!(stdin, "{init_req}").unwrap();
+    writeln!(
+        stdin,
+        r#"{{"jsonrpc":"2.0","method":"notifications/initialized"}}"#
+    )
+    .unwrap();
+    writeln!(
+        stdin,
+        r#"{{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{{}}}}"#
+    )
+    .unwrap();
+
+    // Read initialize response.
+    let mut line = String::new();
+    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()),
+        Some(1),
+        "unexpected id in initialize response: {init}"
+    );
+    assert!(
+        init.get("result").is_some(),
+        "initialize result missing: {init}"
+    );
+
+    // Read tools/list response.
+    line.clear();
+    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()),
+        Some(2),
+        "unexpected id in tools/list response: {list}"
+    );
+    let tools = list["result"]["tools"]
+        .as_array()
+        .expect("tools/list result.tools must be an array");
+    assert_eq!(
+        tools.len(),
+        8,
+        "expected 8 tools (schema, doctor, search, bulk_search, ask, fetch, ingest_file, ingest_stdin), got {}: {list}",
+        tools.len()
+    );
+
+    // Gracefully close stdin so the server shuts down cleanly.
+    drop(stdin);
+    let _ = child.wait().unwrap();
+}

crates/kebab-cli/tests/cli_readonly_quiet.rs

@@ -0,0 +1,183 @@
+//! Integration tests for `--readonly` and `--quiet` global flags (fb-28).
+
+use std::io::Write;
+use std::process::Command;
+
+fn kebab_bin() -> std::path::PathBuf {
+    let manifest = env!("CARGO_MANIFEST_DIR");
+    std::path::PathBuf::from(manifest)
+        .parent()
+        .unwrap()
+        .parent()
+        .unwrap()
+        .join("target/debug/kebab")
+}
+
+fn fixture_workspace() -> (tempfile::TempDir, std::path::PathBuf) {
+    let tmp = tempfile::tempdir().unwrap();
+    let ws = tmp.path().join("workspace");
+    std::fs::create_dir_all(&ws).unwrap();
+    let mut a = std::fs::File::create(ws.join("a.md")).unwrap();
+    writeln!(a, "# Alpha\n\nfirst doc").unwrap();
+    (tmp, ws)
+}
+
+fn xdg_envs(tmp_path: &std::path::Path) -> [(&'static str, std::path::PathBuf); 4] {
+    [
+        ("XDG_CONFIG_HOME", tmp_path.join("cfg")),
+        ("XDG_DATA_HOME", tmp_path.join("data")),
+        ("XDG_CACHE_HOME", tmp_path.join("cache")),
+        ("XDG_STATE_HOME", tmp_path.join("state")),
+    ]
+}
+
+#[test]
+fn readonly_flag_blocks_ingest() {
+    let (tmp, ws) = fixture_workspace();
+    let out = Command::new(kebab_bin())
+        .args(["--readonly", "ingest", "--root", ws.to_str().unwrap()])
+        .envs(xdg_envs(tmp.path()))
+        .output()
+        .unwrap();
+
+    assert_eq!(out.status.code(), Some(1), "expected exit 1");
+    let stderr = String::from_utf8_lossy(&out.stderr);
+    assert!(
+        stderr.contains("readonly mode"),
+        "expected 'readonly mode' in stderr, got: {stderr}"
+    );
+}
+
+#[test]
+fn readonly_flag_blocks_ingest_file() {
+    let (tmp, ws) = fixture_workspace();
+    let file = ws.join("a.md");
+    let out = Command::new(kebab_bin())
+        .args(["--readonly", "ingest-file", file.to_str().unwrap()])
+        .envs(xdg_envs(tmp.path()))
+        .output()
+        .unwrap();
+
+    assert_eq!(out.status.code(), Some(1), "expected exit 1");
+    let stderr = String::from_utf8_lossy(&out.stderr);
+    assert!(stderr.contains("readonly mode"), "stderr: {stderr}");
+}
+
+#[test]
+fn readonly_flag_blocks_ingest_stdin() {
+    let (tmp, _ws) = fixture_workspace();
+    let out = Command::new(kebab_bin())
+        .args(["--readonly", "ingest-stdin", "--title", "test"])
+        .env("KEBAB_READONLY", "1")
+        .envs(xdg_envs(tmp.path()))
+        .stdin(std::process::Stdio::null())
+        .output()
+        .unwrap();
+
+    assert_eq!(out.status.code(), Some(1), "expected exit 1");
+    let stderr = String::from_utf8_lossy(&out.stderr);
+    assert!(stderr.contains("readonly mode"), "stderr: {stderr}");
+}
+
+#[test]
+fn readonly_flag_blocks_reset() {
+    let (tmp, _ws) = fixture_workspace();
+    let out = Command::new(kebab_bin())
+        .args(["--readonly", "reset", "--data-only", "--yes"])
+        .envs(xdg_envs(tmp.path()))
+        .output()
+        .unwrap();
+
+    assert_eq!(out.status.code(), Some(1), "expected exit 1");
+    let stderr = String::from_utf8_lossy(&out.stderr);
+    assert!(stderr.contains("readonly mode"), "stderr: {stderr}");
+}
+
+#[test]
+fn kebab_readonly_env_blocks_ingest() {
+    let (tmp, ws) = fixture_workspace();
+    let out = Command::new(kebab_bin())
+        .args(["ingest", "--root", ws.to_str().unwrap()])
+        .env("KEBAB_READONLY", "1")
+        .envs(xdg_envs(tmp.path()))
+        .output()
+        .unwrap();
+
+    assert_eq!(out.status.code(), Some(1), "expected exit 1");
+    let stderr = String::from_utf8_lossy(&out.stderr);
+    assert!(stderr.contains("readonly mode"), "stderr: {stderr}");
+}
+
+#[test]
+fn readonly_json_mode_emits_error_v1() {
+    let (tmp, ws) = fixture_workspace();
+    let out = Command::new(kebab_bin())
+        .args(["--readonly", "--json", "ingest", "--root", ws.to_str().unwrap()])
+        .envs(xdg_envs(tmp.path()))
+        .output()
+        .unwrap();
+
+    assert_eq!(out.status.code(), Some(1), "expected exit 1");
+    let stderr = String::from_utf8_lossy(&out.stderr);
+    let v: serde_json::Value = serde_json::from_str(stderr.trim())
+        .unwrap_or_else(|e| panic!("expected error.v1 JSON on stderr, got {stderr:?}: {e}"));
+    assert_eq!(
+        v.get("schema_version").and_then(|s| s.as_str()),
+        Some("error.v1"),
+        "expected schema_version=error.v1"
+    );
+    assert_eq!(
+        v.get("code").and_then(|s| s.as_str()),
+        Some("readonly_mode"),
+        "expected code=readonly_mode"
+    );
+}
+
+#[test]
+fn quiet_flag_suppresses_progress_stderr() {
+    let (tmp, ws) = fixture_workspace();
+    let out = Command::new(kebab_bin())
+        .args(["--quiet", "ingest", "--root", ws.to_str().unwrap()])
+        .envs(xdg_envs(tmp.path()))
+        .output()
+        .unwrap();
+
+    assert!(
+        out.status.success(),
+        "exit: {:?}, stderr: {}",
+        out.status.code(),
+        String::from_utf8_lossy(&out.stderr)
+    );
+    let stderr = String::from_utf8_lossy(&out.stderr);
+    assert!(
+        stderr.is_empty(),
+        "expected empty stderr with --quiet, got: {stderr}"
+    );
+    let stdout = String::from_utf8_lossy(&out.stdout);
+    assert!(
+        stdout.contains("scanned"),
+        "expected report summary on stdout, got: {stdout}"
+    );
+}
+
+#[test]
+fn quiet_with_json_stdout_has_report_stderr_is_empty() {
+    let (tmp, ws) = fixture_workspace();
+    let out = Command::new(kebab_bin())
+        .args(["--quiet", "--json", "ingest", "--root", ws.to_str().unwrap()])
+        .envs(xdg_envs(tmp.path()))
+        .output()
+        .unwrap();
+
+    assert!(out.status.success(), "stderr: {}", String::from_utf8_lossy(&out.stderr));
+    let stderr = String::from_utf8_lossy(&out.stderr);
+    assert!(stderr.is_empty(), "expected empty stderr, got: {stderr}");
+    let stdout = String::from_utf8_lossy(&out.stdout);
+    let last_line = stdout.lines().last().unwrap_or("");
+    let v: serde_json::Value = serde_json::from_str(last_line)
+        .unwrap_or_else(|e| panic!("expected JSON on stdout last line, got {last_line:?}: {e}"));
+    assert_eq!(
+        v.get("schema_version").and_then(|s| s.as_str()),
+        Some("ingest_report.v1")
+    );
+}

crates/kebab-cli/tests/cli_schema.rs

@@ -92,8 +92,8 @@ fn cli_schema_json_emits_schema_v1() {
     );
     assert_eq!(
         caps.get("mcp_server").and_then(|b| b.as_bool()),
-        Some(false),
-        "capabilities.mcp_server must be false (not yet shipped)"
+        Some(true),
+        "capabilities.mcp_server must be true (fb-30)"
     );
 }
 

crates/kebab-cli/tests/common/mod.rs

@@ -0,0 +1,243 @@
+//! Shared CLI integration-test helpers.
+//!
+//! Each consumer (`tests/wire_search_stale.rs`, `tests/wire_ask_stale.rs`)
+//! does `mod common;` and calls these via `common::write_config(...)`,
+//! `common::ingest(...)`, `common::backdate_updated_at(...)`.
+//!
+//! `#![allow(dead_code)]` because each consumer typically uses only a
+//! subset of the helpers; rustc would otherwise warn about the unused
+//! ones in any single consumer's compilation.
+
+#![allow(dead_code)]
+
+use std::fs;
+use std::path::{Path, PathBuf};
+use std::process::Command;
+
+/// Build a `config.toml` text under `dir`. `workspace_root` and
+/// `data_dir` live inside `dir`. `stale_threshold_days` is plumbed
+/// into `[search]` so the staleness post-process can fire.
+///
+/// Returns `(cfg_path, workspace_dir, data_dir)`.
+pub fn write_config(dir: &Path, stale_threshold_days: u32) -> (PathBuf, PathBuf, PathBuf) {
+    write_config_with_llm_model(dir, stale_threshold_days, "none")
+}
+
+/// Like [`write_config`] but lets the caller pin a specific
+/// `[models.llm].model` value — needed by `wire_ask_stale.rs` which
+/// hits a real Ollama and wants `gemma4:e4b` instead of `none`.
+pub fn write_config_with_llm_model(
+    dir: &Path,
+    stale_threshold_days: u32,
+    llm_model: &str,
+) -> (PathBuf, PathBuf, PathBuf) {
+    let workspace = dir.join("workspace");
+    let data = dir.join("data");
+    fs::create_dir_all(&workspace).unwrap();
+    fs::create_dir_all(&data).unwrap();
+
+    let cfg_path = dir.join("config.toml");
+    fs::write(
+        &cfg_path,
+        format!(
+            r#"schema_version = 1
+
+[workspace]
+root = "{workspace}"
+exclude = [".git/**"]
+
+[storage]
+data_dir = "{data}"
+sqlite = "{{data_dir}}/kebab.sqlite"
+vector_dir = "{{data_dir}}/lancedb"
+asset_dir = "{{data_dir}}/assets"
+artifact_dir = "{{data_dir}}/artifacts"
+model_dir = "{{data_dir}}/models"
+runs_dir = "{{data_dir}}/runs"
+copy_threshold_mb = 100
+
+[indexing]
+max_parallel_extractors = 2
+max_parallel_embeddings = 1
+watch_filesystem = false
+
+[chunking]
+target_tokens = 80
+overlap_tokens = 20
+respect_markdown_headings = true
+chunker_version = "md-heading-v1"
+
+[models.embedding]
+provider = "none"
+model = "none"
+version = "v0"
+dimensions = 0
+batch_size = 1
+
+[models.llm]
+provider = "ollama"
+model = "{llm_model}"
+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
+stale_threshold_days = {stale_threshold_days}
+
+[rag]
+prompt_template_version = "rag-v1"
+score_gate = 0.30
+explain_default = false
+max_context_tokens = 8000
+"#,
+            workspace = workspace.display(),
+            data = data.display(),
+            llm_model = llm_model,
+            stale_threshold_days = stale_threshold_days,
+        ),
+    )
+    .unwrap();
+    (cfg_path, workspace, data)
+}
+
+/// Run `kebab ingest --root <workspace>` against the given config.
+/// Asserts success — failures abort the calling test.
+pub fn ingest(cfg: &Path, workspace: &Path) {
+    let bin = env!("CARGO_BIN_EXE_kebab");
+    let out = Command::new(bin)
+        .args([
+            "--config",
+            cfg.to_str().unwrap(),
+            "ingest",
+            "--root",
+            workspace.to_str().unwrap(),
+        ])
+        .output()
+        .unwrap();
+    assert!(
+        out.status.success(),
+        "ingest failed: stderr={}",
+        String::from_utf8_lossy(&out.stderr)
+    );
+}
+
+/// p9-fb-34: invoke `kebab search` with arbitrary trailing flags +
+/// query, capture stdout + stderr. Caller is responsible for
+/// supplying `--mode lexical` / `--json` etc. as needed; this helper
+/// stays unopinionated so a single test can exercise both wire shapes
+/// (JSON wrapper + plain stderr hint). Asserts the binary exited 0;
+/// non-zero exits fail the test with stderr included.
+pub fn run_search_with_args(cfg: &Path, args: &[&str]) -> (String, String) {
+    let bin = env!("CARGO_BIN_EXE_kebab");
+    let mut cmd = Command::new(bin);
+    cmd.arg("--config").arg(cfg).arg("search");
+    cmd.args(args);
+    let out = cmd.output().expect("kebab search");
+    assert!(
+        out.status.success(),
+        "search failed: args={args:?} stderr={}",
+        String::from_utf8_lossy(&out.stderr)
+    );
+    (
+        String::from_utf8_lossy(&out.stdout).to_string(),
+        String::from_utf8_lossy(&out.stderr).to_string(),
+    )
+}
+
+/// p9-fb-33: invoke `kebab ask --stream --mode lexical <query>` and
+/// capture stdout + stderr. Lexical mode skips embeddings (matches
+/// `wire_ask_stale.rs::run_ask_lexical`). Caller asserts on the
+/// resulting (stdout, stderr) pair.
+pub fn run_ask_stream(cfg: &Path, query: &str) -> (String, String) {
+    let bin = env!("CARGO_BIN_EXE_kebab");
+    let out = Command::new(bin)
+        .args([
+            "--config",
+            cfg.to_str().unwrap(),
+            "ask",
+            "--stream",
+            "--mode",
+            "lexical",
+            query,
+        ])
+        .output()
+        .expect("kebab ask --stream");
+    (
+        String::from_utf8_lossy(&out.stdout).to_string(),
+        String::from_utf8_lossy(&out.stderr).to_string(),
+    )
+}
+
+/// p9-fb-33: invoke `kebab --json ask --mode lexical <query>` (no
+/// `--stream`) — used by `wire_ask_stream::non_stream_path_unchanged`
+/// to confirm the non-streaming JSON path still emits a single
+/// `answer.v1` line on stdout. Returns stdout only (mirrors
+/// `wire_ask_stale.rs::run_ask_lexical(json=true)` minus the
+/// `Output` indirection).
+pub fn run_ask_json(cfg: &Path, query: &str) -> String {
+    let bin = env!("CARGO_BIN_EXE_kebab");
+    let out = Command::new(bin)
+        .args([
+            "--config",
+            cfg.to_str().unwrap(),
+            "--json",
+            "ask",
+            "--mode",
+            "lexical",
+            query,
+        ])
+        .output()
+        .expect("kebab ask --json");
+    String::from_utf8_lossy(&out.stdout).to_string()
+}
+
+/// p9-fb-35: invoke `kebab fetch` with arbitrary trailing flags,
+/// capture stdout + stderr. Caller is responsible for supplying
+/// `--json` (global flag) before the subcommand position via the
+/// `args` slice (e.g. `&["--json", "chunk", &id]`). Asserts the
+/// binary exited 0; non-zero exits fail the test with stderr
+/// included — for negative-path tests (unknown chunk_id etc.) drive
+/// the binary directly via `std::process::Command`.
+pub fn run_fetch_with_args(cfg: &Path, args: &[&str]) -> (String, String) {
+    let bin = env!("CARGO_BIN_EXE_kebab");
+    let mut cmd = Command::new(bin);
+    cmd.arg("--config").arg(cfg).arg("fetch");
+    cmd.args(args);
+    let out = cmd.output().expect("kebab fetch");
+    assert!(
+        out.status.success(),
+        "fetch failed: args={args:?} stderr={}",
+        String::from_utf8_lossy(&out.stderr)
+    );
+    (
+        String::from_utf8_lossy(&out.stdout).to_string(),
+        String::from_utf8_lossy(&out.stderr).to_string(),
+    )
+}
+
+/// Rewrite `documents.updated_at` for one workspace path to
+/// `now - days_ago` (RFC3339 UTC). Mirrors
+/// `kebab-app/tests/common/mod.rs::backdate_document_updated_at`.
+/// Asserts exactly one row is updated — typo-proofs the workspace path.
+pub fn backdate_updated_at(data_dir: &Path, workspace_path: &str, days_ago: i64) {
+    let backdated = (time::OffsetDateTime::now_utc() - time::Duration::days(days_ago))
+        .format(&time::format_description::well_known::Rfc3339)
+        .expect("format backdated updated_at");
+    let db_path = data_dir.join("kebab.sqlite");
+    let conn = rusqlite::Connection::open(&db_path).expect("open kebab.sqlite");
+    let updated = conn
+        .execute(
+            "UPDATE documents SET updated_at = ?1 WHERE workspace_path = ?2",
+            rusqlite::params![backdated, workspace_path],
+        )
+        .expect("UPDATE documents.updated_at");
+    assert_eq!(
+        updated, 1,
+        "backdate_updated_at: expected to update exactly 1 row for {workspace_path}, got {updated}"
+    );
+}

crates/kebab-cli/tests/ingest_progress_cli.rs

@@ -162,3 +162,32 @@ fn ingest_json_progress_lines_carry_kind_and_ts() {
     assert!(saw_scan_started, "missing scan_started event");
     assert!(saw_completed, "missing completed event");
 }
+
+#[test]
+fn kebab_progress_plain_env_emits_append_lines() {
+    // KEBAB_PROGRESS=plain forces non-TTY branch even in TTY-emulated envs.
+    // In subprocess tests there's no TTY anyway, so this primarily verifies
+    // the env var is accepted and the non-TTY path still works.
+    let (tmp, ws) = fixture_workspace();
+    let out = Command::new(kebab_bin())
+        .args(["ingest", "--root", ws.to_str().unwrap()])
+        .env("KEBAB_PROGRESS", "plain")
+        .envs(xdg_envs(tmp.path()))
+        .output()
+        .unwrap();
+
+    assert!(
+        out.status.success(),
+        "stderr: {}",
+        String::from_utf8_lossy(&out.stderr)
+    );
+    let stderr = String::from_utf8_lossy(&out.stderr);
+    assert!(
+        stderr.contains("ingest: scanning"),
+        "expected 'ingest: scanning' in stderr, got: {stderr}"
+    );
+    assert!(
+        stderr.contains("ingest: complete"),
+        "expected 'ingest: complete' in stderr, got: {stderr}"
+    );
+}

crates/kebab-cli/tests/wire_ask_stale.rs

@@ -0,0 +1,102 @@
+//! p9-fb-32: CLI ask output — JSON path emits `indexed_at` + `stale`
+//! on each citation; plain output prefixes stale citations with
+//! `[stale]` (yellow on TTY).
+//!
+//! These end-to-end checks exercise `kebab ask`, which requires a real
+//! Ollama on `127.0.0.1:11434` (same constraint as
+//! `kebab-app/tests/ask_smoke.rs`). Both tests are therefore
+//! `#[ignore]` by default — run with
+//! `cargo test -p kebab-cli --test wire_ask_stale -- --ignored`
+//! against a live Ollama.
+//!
+//! The `[stale]` rendering logic itself is also covered by a unit test
+//! in `kebab-cli/src/main.rs` (`tests::plain_marks_stale_citation_*`)
+//! that constructs a synthetic `Answer` and pipes it through
+//! `render_ask_plain_citations` — that path is the always-on guard.
+//!
+//! Shared TempDir / ingest / backdate helpers live in
+//! `tests/common/mod.rs`; see also `wire_search_stale.rs`.
+
+mod common;
+
+use std::fs;
+use std::path::Path;
+use std::process::Command;
+
+/// Run `kebab ask` in lexical mode (no embedding required). `json`
+/// toggles `--json`. The caller asserts on the resulting stdout.
+fn run_ask_lexical(cfg: &Path, query: &str, json: bool) -> std::process::Output {
+    let bin = env!("CARGO_BIN_EXE_kebab");
+    let mut cmd = Command::new(bin);
+    cmd.arg("--config").arg(cfg);
+    if json {
+        cmd.arg("--json");
+    }
+    cmd.args(["ask", "--mode", "lexical", query]);
+    cmd.output().unwrap()
+}
+
+#[test]
+#[ignore = "requires real Ollama on 127.0.0.1:11434"]
+fn ask_json_citations_include_indexed_at_and_stale() {
+    let dir = tempfile::tempdir().unwrap();
+    let (cfg, workspace, data) = common::write_config_with_llm_model(dir.path(), 30, "gemma4:e4b");
+    fs::write(workspace.join("a.md"), "# T\n\napples are fruit\n").unwrap();
+    common::ingest(&cfg, &workspace);
+    common::backdate_updated_at(&data, "a.md", 60);
+
+    // ask returns exit 1 on refusal; the JSON envelope still goes to
+    // stdout. Don't assert on `status.success()` — accept either path
+    // and require the citations array to be present + structurally valid.
+    let out = run_ask_lexical(&cfg, "what about apples", true);
+    let stdout = String::from_utf8_lossy(&out.stdout);
+    let answer: serde_json::Value = serde_json::from_str(stdout.trim())
+        .unwrap_or_else(|e| panic!("expected JSON answer, got {stdout:?}: {e}"));
+    let cits = answer["citations"]
+        .as_array()
+        .unwrap_or_else(|| panic!("expected citations array, got {answer}"));
+    if let Some(cit) = cits.first() {
+        // Schema fields are always present on a structurally-valid
+        // AnswerCitation (serde-derived per Task 2 + Task 8).
+        assert!(
+            cit.get("indexed_at").is_some(),
+            "missing indexed_at on citation: {cit}"
+        );
+        assert!(
+            cit.get("stale").is_some(),
+            "missing stale on citation: {cit}"
+        );
+        assert_eq!(
+            cit["stale"], true,
+            "doc backdated 60d at threshold 30d must be stale: {cit}"
+        );
+    }
+    // If the model refused with zero citations the schema-shape claim
+    // is vacuously true; the unit-test path
+    // (`tests::plain_marks_stale_citation_*` in main.rs) is the
+    // always-on guard.
+}
+
+#[test]
+#[ignore = "requires real Ollama on 127.0.0.1:11434"]
+fn ask_plain_marks_stale_citation() {
+    let dir = tempfile::tempdir().unwrap();
+    let (cfg, workspace, data) = common::write_config_with_llm_model(dir.path(), 30, "gemma4:e4b");
+    fs::write(workspace.join("a.md"), "# T\n\napples are fruit\n").unwrap();
+    common::ingest(&cfg, &workspace);
+    common::backdate_updated_at(&data, "a.md", 60);
+
+    // Refusal exits 1 — that's still fine here, the renderer prints
+    // the citation block before the refusal exit when citations exist.
+    // If the model refused with zero citations, this test is
+    // best-effort (skip the assert): the unit-test path in main.rs
+    // (`tests::plain_marks_stale_citation_*`) is the always-on guard.
+    let out = run_ask_lexical(&cfg, "what about apples", false);
+    let stdout = String::from_utf8_lossy(&out.stdout);
+    if stdout.contains("근거:") {
+        assert!(
+            stdout.contains("[stale]"),
+            "stale tag missing in plain ask output:\n{stdout}"
+        );
+    }
+}

crates/kebab-cli/tests/wire_ask_stream.rs

@@ -0,0 +1,241 @@
+//! p9-fb-33: CLI streaming surface — stderr ndjson `answer_event.v1`
+//! events while the answer streams; final stdout line is the existing
+//! `answer.v1` (backwards compat with the non-`--stream` path).
+//!
+//! These end-to-end checks exercise `kebab ask --stream`, which
+//! requires a real Ollama on `127.0.0.1:11434` (same constraint as
+//! `wire_ask_stale.rs` + `kebab-app/tests/ask_smoke.rs`). All three
+//! tests are therefore `#[ignore]` by default — run with
+//! `cargo test -p kebab-cli --test wire_ask_stream -- --ignored`
+//! against a live Ollama with `gemma4:e4b` pulled.
+//!
+//! The `BrokenPipe → cancel` test (Task 7 of the fb-33 plan) verifies
+//! that closing the stderr reader propagates SendError through the
+//! pipeline so the child terminates instead of hanging. That's the
+//! main thing the integration test layer can prove that unit tests
+//! can't — pipeline cancel is a cross-process concern.
+//!
+//! Shared TempDir / ingest helpers live in `tests/common/mod.rs`.
+
+mod common;
+
+use std::fs;
+use std::path::Path;
+
+use serde_json::Value;
+
+/// Drop `[rag].score_gate` to ~0 in the test config so the
+/// score-gate refusal path doesn't short-circuit the LLM call.
+/// Lexical retrieval against a one-doc corpus produces tiny fusion
+/// scores (well below the default 0.30 gate); the pipeline would
+/// take the `refuse_score_gate` early-return — which does not emit
+/// a `Final` event — making the streaming-event ordering assertion
+/// vacuous. Lower the gate so the LLM actually runs.
+fn relax_score_gate(cfg: &Path) {
+    let body = fs::read_to_string(cfg).expect("read config.toml");
+    let body = body.replace("score_gate = 0.30", "score_gate = 0.0");
+    fs::write(cfg, body).expect("write relaxed config.toml");
+}
+
+#[test]
+#[ignore = "requires real Ollama on 127.0.0.1:11434"]
+fn stream_emits_ndjson_events_on_stderr() {
+    let dir = tempfile::tempdir().unwrap();
+    let (cfg, workspace, _data) =
+        common::write_config_with_llm_model(dir.path(), 30, "gemma4:e4b");
+    relax_score_gate(&cfg);
+    fs::write(
+        workspace.join("a.md"),
+        "# T\n\nrust ownership is a memory model.\n",
+    )
+    .unwrap();
+    common::ingest(&cfg, &workspace);
+
+    let (stdout, stderr) = common::run_ask_stream(&cfg, "ownership");
+
+    // stderr: every non-empty line should parse as JSON with
+    // schema_version == "answer_event.v1" and a recognized kind.
+    let mut kinds: Vec<String> = vec![];
+    for line in stderr.lines() {
+        if line.trim().is_empty() {
+            continue;
+        }
+        let v: Value = serde_json::from_str(line)
+            .unwrap_or_else(|e| panic!("non-JSON stderr line: {line:?}: {e}"));
+        assert_eq!(v["schema_version"], "answer_event.v1");
+        let kind = v["kind"].as_str().expect("kind").to_string();
+        assert!(
+            matches!(kind.as_str(), "retrieval_done" | "token" | "final"),
+            "unexpected kind: {kind}"
+        );
+        assert!(v["ts"].is_string(), "ts must be RFC3339 string");
+        kinds.push(kind);
+    }
+
+    // First event must be retrieval_done. Last must be final.
+    // Note: this test only exercises the LLM-running path which always
+    // closes with `final`. score-gate / no-chunks refusal paths emit
+    // only `retrieval_done` and skip `final` — that's why the test uses
+    // `relax_score_gate()` above to force the LLM path. See
+    // `stream_score_gate_refusal_emits_only_retrieval_done` for the
+    // refusal-path coverage.
+    assert_eq!(
+        kinds.first().map(String::as_str),
+        Some("retrieval_done"),
+        "first event must be retrieval_done, all kinds: {kinds:?}"
+    );
+    assert_eq!(
+        kinds.last().map(String::as_str),
+        Some("final"),
+        "last event must be final, all kinds: {kinds:?}"
+    );
+
+    // stdout: last line is answer.v1 (backwards compat with the
+    // non-streaming path — same wire shape, just emitted after the
+    // ndjson event stream rather than instead of it).
+    let final_line = stdout
+        .lines()
+        .last()
+        .expect("stdout has at least one line");
+    let answer: Value =
+        serde_json::from_str(final_line).expect("stdout final line = answer.v1");
+    assert_eq!(answer["schema_version"], "answer.v1");
+}
+
+#[test]
+#[ignore = "requires real Ollama on 127.0.0.1:11434"]
+fn non_stream_path_unchanged() {
+    // Verify that the non-streaming JSON path (no `--stream`) still
+    // emits a single `answer.v1` line on stdout — fb-33 must not
+    // perturb the existing wire surface.
+    let dir = tempfile::tempdir().unwrap();
+    let (cfg, workspace, _data) =
+        common::write_config_with_llm_model(dir.path(), 30, "gemma4:e4b");
+    relax_score_gate(&cfg);
+    fs::write(
+        workspace.join("a.md"),
+        "# T\n\nrust ownership is a memory model.\n",
+    )
+    .unwrap();
+    common::ingest(&cfg, &workspace);
+
+    let stdout = common::run_ask_json(&cfg, "ownership");
+    let v: Value = serde_json::from_str(stdout.trim())
+        .unwrap_or_else(|e| panic!("expected answer.v1, got {stdout:?}: {e}"));
+    assert_eq!(v["schema_version"], "answer.v1");
+}
+
+// p9-fb-33 (Task 7): BrokenPipe → cancel propagation. Spawn the
+// binary, read the first stderr line (retrieval_done), drop the
+// reader. The pipeline's next `Token` send returns SendError, the
+// cancel branch fires, child.wait() returns instead of blocking
+// forever. The key invariant is *liveness* — that `wait()` returns
+// in bounded time. Don't assert exit code: refusal is exit 1, but
+// the child may also exit 0 if the LLM happened to finish before
+// cancel propagated.
+#[test]
+#[ignore = "requires real Ollama on 127.0.0.1:11434 + writes to a closed pipe"]
+fn stream_cancels_when_stderr_closes() {
+    use std::io::{BufRead, BufReader};
+    use std::process::{Command, Stdio};
+
+    let dir = tempfile::tempdir().unwrap();
+    let (cfg, workspace, _data) =
+        common::write_config_with_llm_model(dir.path(), 30, "gemma4:e4b");
+    relax_score_gate(&cfg);
+    fs::write(
+        workspace.join("a.md"),
+        "# T\n\nrust ownership is a memory model. it tracks lifetimes.\n",
+    )
+    .unwrap();
+    common::ingest(&cfg, &workspace);
+
+    let bin = env!("CARGO_BIN_EXE_kebab");
+    let mut child = Command::new(bin)
+        .args([
+            "--config",
+            cfg.to_str().unwrap(),
+            "ask",
+            "--stream",
+            "--mode",
+            "lexical",
+            "ownership",
+        ])
+        .stdout(Stdio::piped())
+        .stderr(Stdio::piped())
+        .spawn()
+        .expect("spawn kebab");
+
+    {
+        let stderr = child.stderr.take().expect("stderr piped");
+        let mut reader = BufReader::new(stderr);
+        let mut first = String::new();
+        reader
+            .read_line(&mut first)
+            .expect("read first stderr line");
+        assert!(
+            first.contains("\"kind\":\"retrieval_done\""),
+            "first event must be retrieval_done, got {first:?}"
+        );
+        // Drop the reader → child's stderr write end will see
+        // BrokenPipe on the next write → main thread drops rx →
+        // worker's pipeline.send returns SendError → cancel.
+    }
+
+    let status = child.wait().expect("child completes after cancel");
+    // Don't assert specific exit code — refusal is exit 1, but child
+    // may also exit 0 if the LLM finished before cancel propagated.
+    // The load-bearing assertion is that wait() returned at all.
+    let _ = status;
+}
+
+// p9-fb-33 (PR #124 round 1, item 4): score-gate refusal path —
+// thin doc + unrelated query trips the default 0.30 score gate
+// before the LLM runs. The pipeline emits only `retrieval_done`
+// on stderr (no `token`, no `final`); stdout still carries the
+// canonical `answer.v1` with `grounded=false`.
+#[test]
+#[ignore = "requires real Ollama on 127.0.0.1:11434"]
+fn stream_score_gate_refusal_emits_only_retrieval_done() {
+    let dir = tempfile::tempdir().unwrap();
+    let (cfg, workspace, _data) =
+        common::write_config_with_llm_model(dir.path(), 30, "gemma4:e4b");
+    // Intentionally NO relax_score_gate — keep the default 0.30
+    // so the thin-doc + unrelated-query combo trips refusal.
+    fs::write(
+        workspace.join("a.md"),
+        "# Title\n\nrust is a language.\n",
+    )
+    .unwrap();
+    common::ingest(&cfg, &workspace);
+
+    let (stdout, stderr) =
+        common::run_ask_stream(&cfg, "completely unrelated topic about cooking pasta");
+
+    let kinds: Vec<String> = stderr
+        .lines()
+        .filter(|l| !l.trim().is_empty())
+        .filter_map(|l| serde_json::from_str::<Value>(l).ok())
+        .filter_map(|v| v["kind"].as_str().map(String::from))
+        .collect();
+
+    // Refusal path: only retrieval_done, no token, no final.
+    assert!(
+        kinds.iter().all(|k| k == "retrieval_done"),
+        "refusal path must emit only retrieval_done, got {kinds:?}"
+    );
+    assert!(
+        !kinds.is_empty(),
+        "expected at least one retrieval_done event, got empty stderr"
+    );
+
+    // Stdout still has answer.v1 with grounded=false.
+    let final_line = stdout
+        .lines()
+        .last()
+        .expect("stdout has at least one line");
+    let answer: Value =
+        serde_json::from_str(final_line).expect("answer.v1");
+    assert_eq!(answer["schema_version"], "answer.v1");
+    assert_eq!(answer["grounded"], false);
+}

crates/kebab-cli/tests/wire_bulk_search.rs

@@ -0,0 +1,174 @@
+//! p9-fb-42: integration tests for `kebab search --bulk`.
+//!
+//! Lexical-only — no fastembed / no Ollama. Each test builds its own
+//! TempDir KB via `common::write_config` + `common::ingest` and drives
+//! `kebab search --bulk` through stdin. Verifies:
+//!
+//! - Two queries over stdin emit per-query ndjson `bulk_search_item.v1` lines.
+//! - Empty stdin returns empty results with zero summary.
+//! - Malformed ndjson exits with code 2 (config_invalid).
+//! - Input over the 100-item cap fails with "max 100" error message.
+//! - Invalid item field (e.g. bad `mode`) emits per-item error and continues.
+
+mod common;
+
+use serde_json::Value;
+use std::fs;
+use std::io::Write;
+use std::process::{Command, Stdio};
+
+fn cargo_bin() -> &'static str {
+    env!("CARGO_BIN_EXE_kebab")
+}
+
+fn run_bulk_with_stdin(cfg: &std::path::Path, stdin_body: &str, json: bool) -> std::process::Output {
+    let mut cmd = Command::new(cargo_bin());
+    cmd.arg("--config").arg(cfg).arg("search").arg("--bulk");
+    if json {
+        cmd.arg("--json");
+    }
+    cmd.stdin(Stdio::piped())
+        .stdout(Stdio::piped())
+        .stderr(Stdio::piped());
+    let mut child = cmd.spawn().expect("spawn kebab");
+    {
+        let mut sin = child.stdin.take().expect("stdin");
+        sin.write_all(stdin_body.as_bytes()).expect("write stdin");
+    }
+    child.wait_with_output().expect("wait")
+}
+
+fn seed_workspace(workspace: &std::path::Path) {
+    fs::write(workspace.join("a.md"), "# Alpha\n\nrust async hello").unwrap();
+    fs::write(workspace.join("b.md"), "# Bravo\n\nbread and kebab").unwrap();
+}
+
+// ---------------------------------------------------------------------------
+// Test 1: Two queries over stdin emit per-query ndjson
+// ---------------------------------------------------------------------------
+
+#[test]
+fn two_query_bulk_emits_per_query_ndjson() {
+    let dir = tempfile::tempdir().unwrap();
+    let (cfg, workspace, _data) = common::write_config(dir.path(), 0);
+    seed_workspace(&workspace);
+    common::ingest(&cfg, &workspace);
+
+    let out = run_bulk_with_stdin(
+        &cfg,
+        "{\"query\":\"rust\",\"mode\":\"lexical\"}\n{\"query\":\"kebab\",\"mode\":\"lexical\"}\n",
+        true,
+    );
+    assert!(
+        out.status.success(),
+        "stderr: {}",
+        String::from_utf8_lossy(&out.stderr)
+    );
+    let stdout = String::from_utf8_lossy(&out.stdout);
+    let lines: Vec<&str> = stdout.lines().filter(|l| !l.trim().is_empty()).collect();
+    assert_eq!(lines.len(), 2, "expected 2 ndjson lines, got {lines:?}");
+    for line in &lines {
+        let v: Value = serde_json::from_str(line).expect("valid JSON line");
+        assert_eq!(v["schema_version"], "bulk_search_item.v1");
+        assert!(v["response"].is_object());
+        assert!(v["error"].is_null());
+    }
+    let stderr = String::from_utf8_lossy(&out.stderr);
+    assert!(
+        stderr.contains("bulk_summary: total=2 succeeded=2 failed=0"),
+        "stderr summary missing: {stderr}"
+    );
+}
+
+// ---------------------------------------------------------------------------
+// Test 2: Empty stdin returns empty results with zero summary
+// ---------------------------------------------------------------------------
+
+#[test]
+fn empty_stdin_returns_empty_results_with_zero_summary() {
+    let dir = tempfile::tempdir().unwrap();
+    let (cfg, workspace, _data) = common::write_config(dir.path(), 0);
+    seed_workspace(&workspace);
+    common::ingest(&cfg, &workspace);
+
+    let out = run_bulk_with_stdin(&cfg, "", true);
+    assert!(out.status.success());
+    let stdout = String::from_utf8_lossy(&out.stdout);
+    assert!(stdout.trim().is_empty(), "expected empty stdout, got: {stdout}");
+    let stderr = String::from_utf8_lossy(&out.stderr);
+    assert!(stderr.contains("bulk_summary: total=0 succeeded=0 failed=0"));
+}
+
+// ---------------------------------------------------------------------------
+// Test 3: Malformed ndjson line emits config_invalid exit 2
+// ---------------------------------------------------------------------------
+
+#[test]
+fn malformed_ndjson_line_emits_config_invalid_exit_2() {
+    let dir = tempfile::tempdir().unwrap();
+    let (cfg, workspace, _data) = common::write_config(dir.path(), 0);
+    seed_workspace(&workspace);
+    common::ingest(&cfg, &workspace);
+
+    let out = run_bulk_with_stdin(&cfg, "not json\n", true);
+    assert_eq!(out.status.code(), Some(2), "expected exit 2");
+    let stderr = String::from_utf8_lossy(&out.stderr);
+    assert!(
+        stderr.contains("config_invalid") || stderr.contains("parse error"),
+        "expected config_invalid or parse error in stderr: {stderr}"
+    );
+}
+
+// ---------------------------------------------------------------------------
+// Test 4: Over cap input (>100) emits error
+// ---------------------------------------------------------------------------
+
+#[test]
+fn over_cap_input_emits_error() {
+    let dir = tempfile::tempdir().unwrap();
+    let (cfg, workspace, _data) = common::write_config(dir.path(), 0);
+    seed_workspace(&workspace);
+    common::ingest(&cfg, &workspace);
+
+    let body: String = (0..101)
+        .map(|_| "{\"query\":\"x\",\"mode\":\"lexical\"}\n")
+        .collect();
+    let out = run_bulk_with_stdin(&cfg, &body, true);
+    // bulk_search_with_config returns Err — surfaces as exit 1 (anyhow chain)
+    // or 2 if classified by error_wire. Accept either, but message must mention `max 100`.
+    assert!(out.status.code().is_some());
+    let stderr = String::from_utf8_lossy(&out.stderr);
+    assert!(
+        stderr.contains("max 100"),
+        "expected 'max 100' in stderr: {stderr}"
+    );
+}
+
+// ---------------------------------------------------------------------------
+// Test 5: Invalid item field (bad mode) emits per-item error and continues
+// ---------------------------------------------------------------------------
+
+#[test]
+fn invalid_item_field_emits_per_item_error_continues() {
+    let dir = tempfile::tempdir().unwrap();
+    let (cfg, workspace, _data) = common::write_config(dir.path(), 0);
+    seed_workspace(&workspace);
+    common::ingest(&cfg, &workspace);
+
+    let out = run_bulk_with_stdin(
+        &cfg,
+        "{\"query\":\"rust\",\"mode\":\"lexical\"}\n{\"query\":\"x\",\"mode\":\"bogus\"}\n",
+        true,
+    );
+    assert!(out.status.success());
+    let stdout = String::from_utf8_lossy(&out.stdout);
+    let lines: Vec<&str> = stdout.lines().filter(|l| !l.trim().is_empty()).collect();
+    assert_eq!(lines.len(), 2);
+    let v0: Value = serde_json::from_str(lines[0]).unwrap();
+    let v1: Value = serde_json::from_str(lines[1]).unwrap();
+    assert!(v0["error"].is_null());
+    assert!(v1["error"].is_object());
+    assert_eq!(v1["error"]["code"], "invalid_input");
+    let stderr = String::from_utf8_lossy(&out.stderr);
+    assert!(stderr.contains("succeeded=1 failed=1"));
+}

crates/kebab-cli/tests/wire_citation_5_variants_unchanged.rs

@@ -0,0 +1,100 @@
+//! p10-1A-1 Task 13: regression — the 5 original Citation variants
+//! (Line, Page, Region, Caption, Time) serialize byte-identically to
+//! pre-Task-1 form.  No spurious `code`, `line_start`, or `symbol` keys
+//! must leak into these variants.
+
+use kebab_core::{Citation, WorkspacePath};
+
+#[test]
+fn line_variant_serialization_unchanged() {
+    let c = Citation::Line {
+        path: WorkspacePath::new("a.md".into()).unwrap(),
+        start: 1,
+        end: 2,
+        section: Some("§14".into()),
+    };
+    let v = serde_json::to_value(&c).unwrap();
+    assert_eq!(v["kind"], "line");
+    assert_eq!(v["start"], 1);
+    assert_eq!(v["end"], 2);
+    assert_eq!(v["section"], "§14");
+    // Must not bleed Code-variant keys.
+    assert!(v.get("line_start").is_none(), "line_start must be absent: {v}");
+    assert!(v.get("symbol").is_none(), "symbol must be absent: {v}");
+    assert!(v.get("code").is_none(), "code must be absent: {v}");
+}
+
+#[test]
+fn line_variant_null_section_omitted() {
+    let c = Citation::Line {
+        path: WorkspacePath::new("b.md".into()).unwrap(),
+        start: 5,
+        end: 10,
+        section: None,
+    };
+    let v = serde_json::to_value(&c).unwrap();
+    assert_eq!(v["kind"], "line");
+    // `section` with None should be omitted (skip_serializing_if = is_none).
+    assert!(v.get("section").is_none() || v["section"].is_null());
+}
+
+#[test]
+fn page_variant_serialization_unchanged() {
+    let c = Citation::Page {
+        path: WorkspacePath::new("a.pdf".into()).unwrap(),
+        page: 13,
+        section: None,
+    };
+    let v = serde_json::to_value(&c).unwrap();
+    assert_eq!(v["kind"], "page");
+    assert_eq!(v["page"], 13);
+    assert!(v.get("line_start").is_none(), "line_start must be absent: {v}");
+    assert!(v.get("symbol").is_none(), "symbol must be absent: {v}");
+}
+
+#[test]
+fn region_variant_serialization_unchanged() {
+    let c = Citation::Region {
+        path: WorkspacePath::new("img.png".into()).unwrap(),
+        x: 10,
+        y: 20,
+        w: 100,
+        h: 200,
+    };
+    let v = serde_json::to_value(&c).unwrap();
+    assert_eq!(v["kind"], "region");
+    assert_eq!(v["x"], 10);
+    assert_eq!(v["y"], 20);
+    assert_eq!(v["w"], 100);
+    assert_eq!(v["h"], 200);
+    assert!(v.get("line_start").is_none(), "line_start must be absent: {v}");
+}
+
+#[test]
+fn caption_variant_serialization_unchanged() {
+    let c = Citation::Caption {
+        path: WorkspacePath::new("a.png".into()).unwrap(),
+        model: "qwen2.5-vl:7b".into(),
+    };
+    let v = serde_json::to_value(&c).unwrap();
+    assert_eq!(v["kind"], "caption");
+    assert_eq!(v["model"], "qwen2.5-vl:7b");
+    assert!(v.get("line_start").is_none(), "line_start must be absent: {v}");
+}
+
+#[test]
+fn time_variant_serialization_unchanged() {
+    let c = Citation::Time {
+        path: WorkspacePath::new("audio.mp3".into()).unwrap(),
+        start_ms: 1000,
+        end_ms: 5000,
+        speaker: Some("Alice".into()),
+    };
+    let v = serde_json::to_value(&c).unwrap();
+    assert_eq!(v["kind"], "time");
+    assert_eq!(v["start_ms"], 1000);
+    assert_eq!(v["end_ms"], 5000);
+    assert_eq!(v["speaker"], "Alice");
+    assert!(v.get("line_start").is_none(), "line_start must be absent: {v}");
+    assert!(v.get("symbol").is_none(), "symbol must be absent: {v}");
+}

crates/kebab-cli/tests/wire_fetch.rs

@@ -0,0 +1,130 @@
+//! p9-fb-35: CLI fetch wire shape + plain output + exit codes.
+//!
+//! Lexical-only — no fastembed / no Ollama. Each test builds its own
+//! TempDir KB via `common::write_config` + `common::ingest` and drives
+//! `kebab fetch` through `common::run_fetch_with_args`. Verifies:
+//!
+//! - `--json fetch chunk <id>` emits the `fetch_result.v1` wrapper
+//!   with `kind = "chunk"` and a populated `chunk` object.
+//! - `--json fetch doc <id> --max-tokens N` flips `truncated: true`
+//!   once the budget binds.
+//! - Unknown `chunk_id` exits non-zero and emits an `error.v1`
+//!   ndjson line on stderr with `code = "chunk_not_found"`.
+
+mod common;
+
+use serde_json::Value;
+use std::fs;
+
+#[test]
+fn fetch_chunk_json_emits_fetch_result_v1() {
+    let dir = tempfile::tempdir().unwrap();
+    let (cfg, workspace, _data) = common::write_config(dir.path(), 30);
+    fs::write(workspace.join("a.md"), "# T\n\napples are red.\n").unwrap();
+    common::ingest(&cfg, &workspace);
+
+    // Find chunk_id via search.
+    let (search_stdout, _) = common::run_search_with_args(
+        &cfg,
+        &["--json", "--mode", "lexical", "--k", "1", "apples"],
+    );
+    let search: Value = serde_json::from_str(search_stdout.trim())
+        .unwrap_or_else(|e| panic!("search not JSON: {search_stdout:?}: {e}"));
+    let chunk_id = search["hits"][0]["chunk_id"]
+        .as_str()
+        .expect("chunk_id on first hit")
+        .to_string();
+
+    let (stdout, _) = common::run_fetch_with_args(
+        &cfg,
+        &["--json", "chunk", &chunk_id],
+    );
+    let v: Value = serde_json::from_str(stdout.trim())
+        .unwrap_or_else(|e| panic!("fetch not JSON: {stdout:?}: {e}"));
+    assert_eq!(v["schema_version"], "fetch_result.v1");
+    assert_eq!(v["kind"], "chunk");
+    assert!(
+        v["chunk"].is_object(),
+        "target chunk must be populated: {v}"
+    );
+    assert_eq!(v["truncated"], false);
+}
+
+#[test]
+fn fetch_doc_json_with_max_tokens_truncates() {
+    let dir = tempfile::tempdir().unwrap();
+    let (cfg, workspace, _data) = common::write_config(dir.path(), 30);
+    let body: String = "Lorem ipsum dolor sit amet. ".repeat(20);
+    fs::write(workspace.join("big.md"), format!("# Big\n\n{body}\n")).unwrap();
+    common::ingest(&cfg, &workspace);
+
+    // Find doc_id via search.
+    let (search_stdout, _) = common::run_search_with_args(
+        &cfg,
+        &["--json", "--mode", "lexical", "--k", "1", "Lorem"],
+    );
+    let search: Value = serde_json::from_str(search_stdout.trim())
+        .unwrap_or_else(|e| panic!("search not JSON: {search_stdout:?}: {e}"));
+    let doc_id = search["hits"][0]["doc_id"]
+        .as_str()
+        .expect("doc_id on first hit")
+        .to_string();
+
+    let (stdout, _) = common::run_fetch_with_args(
+        &cfg,
+        &["--json", "doc", &doc_id, "--max-tokens", "20"],
+    );
+    let v: Value = serde_json::from_str(stdout.trim())
+        .unwrap_or_else(|e| panic!("fetch not JSON: {stdout:?}: {e}"));
+    assert_eq!(v["kind"], "doc");
+    assert_eq!(
+        v["truncated"], true,
+        "20-token cap must trip truncation: {v}"
+    );
+}
+
+#[test]
+fn fetch_chunk_unknown_id_exits_with_error_v1() {
+    let dir = tempfile::tempdir().unwrap();
+    let (cfg, _workspace, _data) = common::write_config(dir.path(), 30);
+
+    // Direct invocation (not via the success-asserting helper) so we
+    // can read stderr on failure — mirrors the stale_cursor test in
+    // `wire_search_response.rs`.
+    let exe = env!("CARGO_BIN_EXE_kebab");
+    let cfg_str = cfg.to_str().expect("utf8");
+    let out = std::process::Command::new(exe)
+        .args([
+            "--config",
+            cfg_str,
+            "--json",
+            "fetch",
+            "chunk",
+            "nonexistent",
+        ])
+        .output()
+        .expect("kebab fetch");
+
+    assert_ne!(out.status.code(), Some(0), "must exit non-zero");
+    let stderr = String::from_utf8_lossy(&out.stderr);
+    let err_line = stderr
+        .lines()
+        .find(|l| {
+            serde_json::from_str::<Value>(l)
+                .ok()
+                .and_then(|v| {
+                    v.get("schema_version")
+                        .and_then(|s| s.as_str())
+                        .map(String::from)
+                })
+                .as_deref()
+                == Some("error.v1")
+        })
+        .unwrap_or_else(|| panic!("no error.v1 line on stderr: {stderr:?}"));
+
+    let v: Value = serde_json::from_str(err_line).expect("error.v1 json");
+    assert_eq!(
+        v["code"], "chunk_not_found",
+        "code must be chunk_not_found: {err_line}"
+    );
+}

crates/kebab-cli/tests/wire_schema_breakdowns.rs

@@ -0,0 +1,57 @@
+//! p9-fb-37: integration tests for `kebab schema --json` extended stats.
+
+mod common;
+
+use serde_json::Value;
+use std::fs;
+use std::process::Command;
+
+fn run_schema(cfg: &std::path::Path) -> Value {
+    let bin = env!("CARGO_BIN_EXE_kebab");
+    let out = Command::new(bin)
+        .args(["--config", cfg.to_str().unwrap(), "schema", "--json"])
+        .output()
+        .expect("run kebab schema");
+    assert!(
+        out.status.success(),
+        "schema failed: stderr={}",
+        String::from_utf8_lossy(&out.stderr)
+    );
+    serde_json::from_slice(&out.stdout).expect("valid JSON")
+}
+
+#[test]
+fn schema_stats_includes_breakdowns_on_fresh_corpus() {
+    let dir = tempfile::tempdir().unwrap();
+    let (cfg, workspace, _data) = common::write_config(dir.path(), 0);
+    // Run a no-op ingest to bring up migrations + create the SQLite file.
+    fs::write(workspace.join("placeholder.md"), "# placeholder\n").unwrap();
+    common::ingest(&cfg, &workspace);
+
+    let v = run_schema(&cfg);
+    let stats = &v["stats"];
+    let m = stats["media_breakdown"].as_object().unwrap();
+    assert_eq!(m.len(), 5, "5 media keys padded");
+    for k in &["markdown", "pdf", "image", "audio", "other"] {
+        assert!(m[*k].is_number(), "media[{k}] is integer");
+    }
+    assert!(stats["lang_breakdown"].is_object());
+    assert!(stats["index_bytes"]["sqlite"].is_number());
+    assert!(stats["index_bytes"]["lancedb"].is_number());
+    assert!(stats["stale_doc_count"].is_number());
+}
+
+#[test]
+fn schema_stats_breakdowns_after_ingest() {
+    let dir = tempfile::tempdir().unwrap();
+    let (cfg, workspace, _data) = common::write_config(dir.path(), 0);
+    fs::write(workspace.join("a.md"), "---\nlang: en\n---\nhello\n").unwrap();
+    fs::write(workspace.join("b.md"), "---\nlang: ko\n---\n안녕\n").unwrap();
+    common::ingest(&cfg, &workspace);
+
+    let v = run_schema(&cfg);
+    let stats = &v["stats"];
+    assert_eq!(stats["media_breakdown"]["markdown"], 2);
+    assert!(stats["lang_breakdown"].is_object());
+    assert!(stats["index_bytes"]["sqlite"].as_u64().unwrap() > 0);
+}

crates/kebab-cli/tests/wire_search_filters.rs

@@ -0,0 +1,306 @@
+//! p9-fb-36: CLI integration tests for search filter flags.
+//!
+//! Lexical-only — no fastembed / no Ollama. Each test builds its own
+//! TempDir KB via `common::write_config` + `common::ingest` and drives
+//! `kebab search` through `common::run_search_with_args` or direct
+//! `Command` invocations. Verifies:
+//!
+//! - `--doc-id <id>` restricts all returned hits to the target document.
+//! - `--ingested-after <bad>` exits non-zero and emits `error.v1` on
+//!   stderr with `code = "config_invalid"`.
+//! - `--media md` (alias) normalises to `markdown` and matches `.md` docs.
+//! - `--tag <tag>` (repeatable, OR-within) filters by frontmatter tags.
+
+mod common;
+
+use serde_json::Value;
+use std::fs;
+use std::process::Command;
+
+// ---------------------------------------------------------------------------
+// Test 1: --doc-id restricts hits to a single document
+// ---------------------------------------------------------------------------
+
+#[test]
+fn search_with_doc_id_filter_returns_only_target_doc() {
+    let dir = tempfile::tempdir().unwrap();
+    let (cfg, workspace, _data) = common::write_config(dir.path(), 30);
+
+    // Two docs that both contain the search term.
+    fs::write(workspace.join("a.md"), "# Alpha\n\nrust ownership rules\n").unwrap();
+    fs::write(workspace.join("b.md"), "# Beta\n\nrust borrow checker\n").unwrap();
+    common::ingest(&cfg, &workspace);
+
+    // First, search without a doc-id filter to find what doc_ids exist.
+    let (stdout, _) = common::run_search_with_args(
+        &cfg,
+        &["--json", "--mode", "lexical", "rust"],
+    );
+    let resp: Value = serde_json::from_str(stdout.trim())
+        .unwrap_or_else(|e| panic!("not JSON: {stdout:?}: {e}"));
+    let hits = resp["hits"].as_array().expect("hits array");
+    assert!(
+        hits.len() >= 2,
+        "expected ≥2 hits from two docs before filter: {resp}"
+    );
+
+    // Grab one doc_id from the results.
+    let target_doc_id = hits[0]["doc_id"]
+        .as_str()
+        .expect("doc_id string")
+        .to_string();
+
+    // Re-search with --doc-id set to the first hit's doc_id.
+    let (stdout2, _) = common::run_search_with_args(
+        &cfg,
+        &[
+            "--json",
+            "--mode",
+            "lexical",
+            "--doc-id",
+            &target_doc_id,
+            "rust",
+        ],
+    );
+    let resp2: Value = serde_json::from_str(stdout2.trim())
+        .unwrap_or_else(|e| panic!("not JSON after filter: {stdout2:?}: {e}"));
+    let filtered_hits = resp2["hits"].as_array().expect("hits array (filtered)");
+
+    assert!(
+        !filtered_hits.is_empty(),
+        "expected at least one hit for the target doc"
+    );
+    for hit in filtered_hits {
+        let got = hit["doc_id"].as_str().expect("doc_id string in hit");
+        assert_eq!(
+            got, target_doc_id,
+            "--doc-id filter must restrict all hits to target doc, got {got}"
+        );
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Test 2: --ingested-after with bad RFC3339 → exit non-zero + error.v1
+// ---------------------------------------------------------------------------
+
+#[test]
+fn search_with_invalid_ingested_after_emits_config_invalid() {
+    let dir = tempfile::tempdir().unwrap();
+    let (cfg, workspace, _data) = common::write_config(dir.path(), 30);
+    fs::write(workspace.join("a.md"), "# T\n\nrust stuff\n").unwrap();
+    common::ingest(&cfg, &workspace);
+
+    let bin = env!("CARGO_BIN_EXE_kebab");
+    let out = Command::new(bin)
+        .args([
+            "--config",
+            cfg.to_str().unwrap(),
+            "--json",
+            "search",
+            "--mode",
+            "lexical",
+            "--ingested-after",
+            "not-a-date",
+            "rust",
+        ])
+        .output()
+        .expect("kebab search --ingested-after bad");
+
+    assert!(
+        !out.status.success(),
+        "expected non-zero exit for invalid --ingested-after, got: status={} stderr={}",
+        out.status,
+        String::from_utf8_lossy(&out.stderr)
+    );
+
+    let stderr = String::from_utf8_lossy(&out.stderr);
+    // Find the error.v1 ndjson line on stderr (one JSON event per line).
+    let err_line = stderr
+        .lines()
+        .find(|l| {
+            serde_json::from_str::<Value>(l)
+                .ok()
+                .and_then(|v| {
+                    v.get("schema_version")
+                        .and_then(|s| s.as_str())
+                        .map(String::from)
+                })
+                .as_deref()
+                == Some("error.v1")
+        })
+        .unwrap_or_else(|| panic!("no error.v1 line on stderr: {stderr:?}"));
+
+    let v: Value = serde_json::from_str(err_line).expect("error.v1 json");
+    assert_eq!(
+        v["code"], "config_invalid",
+        "code must be config_invalid for bad RFC3339: {err_line}"
+    );
+}
+
+// ---------------------------------------------------------------------------
+// Test 3: --media md (alias) normalises to markdown and matches .md docs
+// ---------------------------------------------------------------------------
+
+#[test]
+fn search_with_media_filter_md_alias_normalizes_to_markdown() {
+    let dir = tempfile::tempdir().unwrap();
+    let (cfg, workspace, _data) = common::write_config(dir.path(), 30);
+
+    // Only a markdown file — the `md` alias should match it.
+    fs::write(workspace.join("notes.md"), "# Notes\n\nrust async programming\n").unwrap();
+    common::ingest(&cfg, &workspace);
+
+    let (stdout, _) = common::run_search_with_args(
+        &cfg,
+        &["--json", "--mode", "lexical", "--media", "md", "rust"],
+    );
+    let resp: Value = serde_json::from_str(stdout.trim())
+        .unwrap_or_else(|e| panic!("not JSON: {stdout:?}: {e}"));
+    let hits = resp["hits"].as_array().expect("hits array");
+
+    assert!(
+        !hits.is_empty(),
+        "--media md must match the markdown doc; got 0 hits: {resp}"
+    );
+}
+
+// ---------------------------------------------------------------------------
+// Test 4: --tag (repeatable, OR-within) filters by frontmatter tags
+// ---------------------------------------------------------------------------
+
+#[test]
+fn search_with_tag_filter_matches_frontmatter_tags() {
+    let dir = tempfile::tempdir().unwrap();
+    let (cfg, workspace, _data) = common::write_config(dir.path(), 30);
+
+    // Doc with `rust` tag.
+    fs::write(
+        workspace.join("rust_doc.md"),
+        "---\ntags: [rust, systems]\n---\n# Rust\n\nrust ownership\n",
+    )
+    .unwrap();
+    // Doc without the tag (but same keyword in body so it appears in
+    // unfiltered results — the tag filter must exclude it).
+    fs::write(
+        workspace.join("other_doc.md"),
+        "# Other\n\nrust programming\n",
+    )
+    .unwrap();
+    common::ingest(&cfg, &workspace);
+
+    // Without filter — both docs must produce hits.
+    let (unfiltered, _) = common::run_search_with_args(
+        &cfg,
+        &["--json", "--mode", "lexical", "rust"],
+    );
+    let uresp: Value = serde_json::from_str(unfiltered.trim())
+        .unwrap_or_else(|e| panic!("not JSON (unfiltered): {unfiltered:?}: {e}"));
+    let uhits = uresp["hits"].as_array().expect("unfiltered hits array");
+    assert!(
+        uhits.len() >= 2,
+        "expected ≥2 hits before tag filter: {uresp}"
+    );
+
+    // With --tag rust — only the tagged doc's hits should appear.
+    let (filtered, _) = common::run_search_with_args(
+        &cfg,
+        &["--json", "--mode", "lexical", "--tag", "rust", "rust"],
+    );
+    let fresp: Value = serde_json::from_str(filtered.trim())
+        .unwrap_or_else(|e| panic!("not JSON (tag-filtered): {filtered:?}: {e}"));
+    let fhits = fresp["hits"].as_array().expect("filtered hits array");
+
+    assert!(
+        !fhits.is_empty(),
+        "--tag rust must match the tagged doc; got 0 hits: {fresp}"
+    );
+
+    // Every returned hit must come from rust_doc.md (the tagged file).
+    for hit in fhits {
+        let path = hit["doc_path"].as_str().unwrap_or("");
+        assert!(
+            path.ends_with("rust_doc.md"),
+            "--tag rust must only return hits from the tagged doc, got path={path}"
+        );
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Test 5: --tag is repeatable (OR-within); two --tag values form an IN-list
+// ---------------------------------------------------------------------------
+
+#[test]
+fn search_with_two_tag_filters_returns_or_within_tags() {
+    // Two docs with different tag sets:
+    //   a.md → tags: [rust]
+    //   b.md → tags: [async]
+    //   c.md → no tags (but same keyword in body)
+    // Search with --tag rust --tag async (OR within --tag).
+    // Expect a.md and b.md, not c.md.
+    let dir = tempfile::tempdir().unwrap();
+    let (cfg, workspace, _data) = common::write_config(dir.path(), 30);
+
+    fs::write(
+        workspace.join("a.md"),
+        "---\ntags: [rust]\n---\n# A\n\nrust systems programming\n",
+    )
+    .unwrap();
+    fs::write(
+        workspace.join("b.md"),
+        "---\ntags: [async]\n---\n# B\n\nrust async programming\n",
+    )
+    .unwrap();
+    fs::write(workspace.join("c.md"), "# C\n\nrust programming\n").unwrap();
+    common::ingest(&cfg, &workspace);
+
+    // Without filter: all three docs produce hits.
+    let (unfiltered, _) = common::run_search_with_args(
+        &cfg,
+        &["--json", "--mode", "lexical", "rust"],
+    );
+    let uresp: Value = serde_json::from_str(unfiltered.trim())
+        .unwrap_or_else(|e| panic!("not JSON (unfiltered): {unfiltered:?}: {e}"));
+    let uhits = uresp["hits"].as_array().expect("unfiltered hits array");
+    assert!(
+        uhits.len() >= 3,
+        "expected ≥3 hits before tag filter: {uresp}"
+    );
+
+    // With --tag rust --tag async: only a.md and b.md should appear.
+    let (filtered, _) = common::run_search_with_args(
+        &cfg,
+        &[
+            "--json", "--mode", "lexical",
+            "--tag", "rust",
+            "--tag", "async",
+            "rust",
+        ],
+    );
+    let fresp: Value = serde_json::from_str(filtered.trim())
+        .unwrap_or_else(|e| panic!("not JSON (two-tag-filtered): {filtered:?}: {e}"));
+    let fhits = fresp["hits"].as_array().expect("filtered hits array");
+
+    assert!(
+        !fhits.is_empty(),
+        "--tag rust --tag async must return hits from tagged docs; got 0: {fresp}"
+    );
+
+    // c.md must not appear — it has no tags.
+    for hit in fhits {
+        let path = hit["doc_path"].as_str().unwrap_or("");
+        assert!(
+            path.ends_with("a.md") || path.ends_with("b.md"),
+            "--tag rust --tag async must only return a.md or b.md, got path={path}"
+        );
+    }
+
+    // Both a.md and b.md must appear (OR, not AND).
+    let paths: Vec<&str> = fhits
+        .iter()
+        .filter_map(|h| h["doc_path"].as_str())
+        .collect();
+    let has_a = paths.iter().any(|p| p.ends_with("a.md"));
+    let has_b = paths.iter().any(|p| p.ends_with("b.md"));
+    assert!(has_a, "--tag rust must include a.md (rust-tagged): paths={paths:?}");
+    assert!(has_b, "--tag async must include b.md (async-tagged): paths={paths:?}");
+}

crates/kebab-cli/tests/wire_search_filters_code.rs

@@ -0,0 +1,72 @@
+//! p10-1A-1 Task 15: CLI accepts --repo and --code-lang flags.
+//!
+//! These tests verify that clap parses the new flags without error.
+//! They drive `kebab search --help` (which exercises flag parsing
+//! via clap's help generation path, exiting 0) or use a minimal
+//! config + `--json` round-trip to verify the flags reach the wire.
+
+use std::process::Command;
+
+fn kebab() -> Command {
+    Command::new(env!("CARGO_BIN_EXE_kebab"))
+}
+
+/// `kebab search --help` must exit 0 and mention `--repo`.
+#[test]
+fn cli_search_help_mentions_repo_flag() {
+    let out = kebab()
+        .args(["search", "--help"])
+        .output()
+        .expect("failed to run kebab");
+    // clap help exits 0.
+    assert!(
+        out.status.success(),
+        "kebab search --help exited non-zero: {:?}",
+        out.status
+    );
+    let stdout = String::from_utf8_lossy(&out.stdout);
+    assert!(
+        stdout.contains("--repo"),
+        "--repo flag must appear in search help output:\n{stdout}"
+    );
+}
+
+/// `kebab search --help` must exit 0 and mention `--code-lang`.
+#[test]
+fn cli_search_help_mentions_code_lang_flag() {
+    let out = kebab()
+        .args(["search", "--help"])
+        .output()
+        .expect("failed to run kebab");
+    assert!(
+        out.status.success(),
+        "kebab search --help exited non-zero: {:?}",
+        out.status
+    );
+    let stdout = String::from_utf8_lossy(&out.stdout);
+    assert!(
+        stdout.contains("--code-lang"),
+        "--code-lang flag must appear in search help output:\n{stdout}"
+    );
+}
+
+/// `kebab search --help` must exit 0 and mention `--media`.
+/// Confirms `--media code` value pathway is available (media is
+/// a free-form Vec<String> that already accepted arbitrary values).
+#[test]
+fn cli_search_help_mentions_media_flag() {
+    let out = kebab()
+        .args(["search", "--help"])
+        .output()
+        .expect("failed to run kebab");
+    assert!(
+        out.status.success(),
+        "kebab search --help exited non-zero: {:?}",
+        out.status
+    );
+    let stdout = String::from_utf8_lossy(&out.stdout);
+    assert!(
+        stdout.contains("--media"),
+        "--media flag must appear in search help output:\n{stdout}"
+    );
+}

crates/kebab-cli/tests/wire_search_hit_no_code_fields.rs

@@ -0,0 +1,47 @@
+//! p10-1A-1 Task 13: regression — markdown SearchHit omits `repo` and
+//! `code_lang` from JSON when both are `None`.
+//!
+//! Proves that adding optional fields to SearchHit does not silently
+//! inject spurious keys into the existing markdown corpus wire shape.
+
+use kebab_core::{
+    Citation, ChunkId, ChunkerVersion, DocumentId, IndexVersion, RetrievalDetail, ScoreKind,
+    SearchHit, WorkspacePath,
+};
+
+#[test]
+fn markdown_hit_omits_repo_and_code_lang() {
+    let hit = SearchHit {
+        rank: 1,
+        chunk_id: ChunkId("c1".into()),
+        doc_id: DocumentId("d1".into()),
+        doc_path: WorkspacePath::new("notes/foo.md".into()).unwrap(),
+        heading_path: vec!["A".into(), "B".into()],
+        section_label: Some("B".into()),
+        snippet: "hi".into(),
+        citation: Citation::Line {
+            path: WorkspacePath::new("notes/foo.md".into()).unwrap(),
+            start: 1,
+            end: 2,
+            section: None,
+        },
+        retrieval: RetrievalDetail::default(),
+        index_version: IndexVersion("v1".into()),
+        embedding_model: None,
+        chunker_version: ChunkerVersion("md-heading-v1".into()),
+        indexed_at: time::OffsetDateTime::UNIX_EPOCH,
+        stale: false,
+        score_kind: ScoreKind::Rrf,
+        repo: None,
+        code_lang: None,
+    };
+    let s = serde_json::to_string(&hit).unwrap();
+    assert!(
+        !s.contains("\"repo\""),
+        "repo should be absent from markdown hit JSON: {s}"
+    );
+    assert!(
+        !s.contains("\"code_lang\""),
+        "code_lang should be absent from markdown hit JSON: {s}"
+    );
+}

crates/kebab-cli/tests/wire_search_response.rs

@@ -0,0 +1,226 @@
+//! p9-fb-34: CLI search wire wrapper + budget controls.
+//!
+//! Lexical-only — no fastembed / no Ollama. Each test builds its own
+//! TempDir KB via `common::write_config` + `common::ingest` and drives
+//! `kebab search` through `common::run_search_with_args`. Verifies:
+//!
+//! - `--json` emits the `search_response.v1` wrapper (hits + cursor +
+//!   truncated).
+//! - `--max-tokens` flips `truncated: true` once the budget binds.
+//! - `--cursor` advances paging (page 2 chunk_ids disjoint from page 1).
+//! - Plain (non-JSON) output prints the `[truncated; ...]` hint to
+//!   stderr (stdout stays the hit list).
+
+mod common;
+
+use serde_json::Value;
+use std::fs;
+
+#[test]
+fn search_json_emits_search_response_v1_wrapper() {
+    let dir = tempfile::tempdir().unwrap();
+    let (cfg, workspace, _data) = common::write_config(dir.path(), 30);
+    fs::write(workspace.join("a.md"), "# T\n\napples are red.\n").unwrap();
+    common::ingest(&cfg, &workspace);
+
+    let (stdout, _stderr) = common::run_search_with_args(
+        &cfg,
+        &["--json", "--mode", "lexical", "apples"],
+    );
+    let v: Value = serde_json::from_str(stdout.trim())
+        .unwrap_or_else(|e| panic!("not JSON: {stdout:?}: {e}"));
+    assert_eq!(v["schema_version"], "search_response.v1");
+    assert!(v["hits"].is_array(), "hits must be array, got {v}");
+    assert!(
+        v["next_cursor"].is_null() || v["next_cursor"].is_string(),
+        "next_cursor must be null or string, got {}",
+        v["next_cursor"]
+    );
+    assert!(
+        v["truncated"].is_boolean(),
+        "truncated must be bool, got {}",
+        v["truncated"]
+    );
+}
+
+#[test]
+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();
+    common::ingest(&cfg, &workspace);
+
+    let (stdout, _stderr) = common::run_search_with_args(
+        &cfg,
+        &["--json", "--mode", "lexical", "--max-tokens", "30", "rust"],
+    );
+    let v: Value = serde_json::from_str(stdout.trim())
+        .unwrap_or_else(|e| panic!("not JSON: {stdout:?}: {e}"));
+    assert_eq!(
+        v["truncated"], true,
+        "30-token cap must trip truncation: {v}"
+    );
+}
+
+#[test]
+fn search_json_cursor_paginates() {
+    let dir = tempfile::tempdir().unwrap();
+    let (cfg, workspace, _data) = common::write_config(dir.path(), 30);
+    for i in 0..6 {
+        fs::write(
+            workspace.join(format!("d{i}.md")),
+            format!("# T{i}\n\nrust topic {i}\n"),
+        )
+        .unwrap();
+    }
+    common::ingest(&cfg, &workspace);
+
+    let (page1, _) = common::run_search_with_args(
+        &cfg,
+        &["--json", "--mode", "lexical", "--k", "2", "rust"],
+    );
+    let v1: Value = serde_json::from_str(page1.trim())
+        .unwrap_or_else(|e| panic!("page1 not JSON: {page1:?}: {e}"));
+    let cursor = v1["next_cursor"]
+        .as_str()
+        .unwrap_or_else(|| panic!("next_cursor missing on page1: {v1}"));
+
+    let (page2, _) = common::run_search_with_args(
+        &cfg,
+        &[
+            "--json",
+            "--mode",
+            "lexical",
+            "--k",
+            "2",
+            "--cursor",
+            cursor,
+            "rust",
+        ],
+    );
+    let v2: Value = serde_json::from_str(page2.trim())
+        .unwrap_or_else(|e| panic!("page2 not JSON: {page2:?}: {e}"));
+
+    let p1_ids: Vec<String> = v1["hits"]
+        .as_array()
+        .expect("page1 hits array")
+        .iter()
+        .map(|h| {
+            h["chunk_id"]
+                .as_str()
+                .expect("chunk_id string")
+                .to_string()
+        })
+        .collect();
+    let p2_ids: Vec<String> = v2["hits"]
+        .as_array()
+        .expect("page2 hits array")
+        .iter()
+        .map(|h| {
+            h["chunk_id"]
+                .as_str()
+                .expect("chunk_id string")
+                .to_string()
+        })
+        .collect();
+    assert!(
+        !p2_ids.is_empty(),
+        "page2 must return at least one hit (cursor advanced past page1)"
+    );
+    assert!(
+        p2_ids.iter().all(|id| !p1_ids.contains(id)),
+        "page2 must not repeat page1 chunk_ids: page1={p1_ids:?} page2={p2_ids:?}"
+    );
+}
+
+#[test]
+fn search_stale_cursor_returns_error_v1_with_stale_cursor_code() {
+    // p9-fb-34 round-1 review: end-to-end wire contract — when the
+    // corpus_revision bumps between cursor issuance and the cursored
+    // search, `kebab --json search --cursor <stale>` must emit an
+    // `error.v1` ndjson line on stderr with `code = "stale_cursor"`.
+    // Pre-fix this returned `code = "generic"` because
+    // `App::search_with_opts` string-formatted the typed payload into
+    // anyhow, losing the structured wrapper.
+    let dir = tempfile::tempdir().unwrap();
+    let (cfg, workspace, _data) = common::write_config(dir.path(), 30);
+    fs::write(workspace.join("a.md"), "# T\n\napples\n").unwrap();
+    common::ingest(&cfg, &workspace);
+
+    // Get a valid cursor first.
+    let (page1_stdout, _) = common::run_search_with_args(
+        &cfg,
+        &["--mode", "lexical", "--json", "--k", "1", "apples"],
+    );
+    let v1: Value = serde_json::from_str(page1_stdout.trim()).expect("json");
+    let cursor = v1["next_cursor"]
+        .as_str()
+        .expect("k=1 page must emit next_cursor — fixture too small if this fails")
+        .to_string();
+
+    // Bump corpus_revision by ingesting a second doc.
+    fs::write(workspace.join("b.md"), "# B\n\nbananas\n").unwrap();
+    common::ingest(&cfg, &workspace);
+
+    // Use the now-stale cursor. Direct invocation (not via the
+    // success-asserting helper) so we can read stderr on failure.
+    let exe = env!("CARGO_BIN_EXE_kebab");
+    let cfg_str = cfg.to_str().expect("utf8");
+    let out = std::process::Command::new(exe)
+        .args([
+            "--config",
+            cfg_str,
+            "--json",
+            "search",
+            "--mode",
+            "lexical",
+            "--json",
+            "--cursor",
+            &cursor,
+            "apples",
+        ])
+        .output()
+        .expect("kebab search --cursor");
+
+    let stderr = String::from_utf8_lossy(&out.stderr);
+    // Find the error.v1 ndjson line on stderr (one event per line).
+    let err_line = stderr
+        .lines()
+        .find(|l| {
+            serde_json::from_str::<Value>(l)
+                .ok()
+                .and_then(|v| {
+                    v.get("schema_version")
+                        .and_then(|s| s.as_str())
+                        .map(String::from)
+                })
+                .as_deref()
+                == Some("error.v1")
+        })
+        .unwrap_or_else(|| panic!("no error.v1 line on stderr: {stderr:?}"));
+
+    let v: Value = serde_json::from_str(err_line).expect("error.v1 json");
+    assert_eq!(
+        v["code"], "stale_cursor",
+        "code must be stale_cursor: {err_line}"
+    );
+}
+
+#[test]
+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();
+    common::ingest(&cfg, &workspace);
+
+    let (_stdout, stderr) = common::run_search_with_args(
+        &cfg,
+        &["--mode", "lexical", "--max-tokens", "30", "rust"],
+    );
+    assert!(
+        stderr.contains("[truncated;"),
+        "stderr must carry truncated hint: {stderr:?}"
+    );
+}

crates/kebab-cli/tests/wire_search_score_kind.rs

@@ -0,0 +1,50 @@
+//! p9-fb-38: integration tests for `search_hit.v1.score_kind`.
+
+mod common;
+
+use serde_json::Value;
+use std::fs;
+
+fn doc_with_term(workspace: &std::path::Path) {
+    fs::write(workspace.join("doc1.md"), "# Title\n\nrust async hello\n").unwrap();
+}
+
+#[test]
+fn lexical_mode_hits_carry_bm25_score_kind() {
+    let dir = tempfile::tempdir().unwrap();
+    let (cfg, workspace, _data) = common::write_config(dir.path(), 0);
+    doc_with_term(&workspace);
+    common::ingest(&cfg, &workspace);
+
+    let (stdout, _stderr) = common::run_search_with_args(
+        &cfg,
+        &["--mode", "lexical", "--json", "rust"],
+    );
+    let v: Value = serde_json::from_str(stdout.trim()).expect("valid JSON");
+    let hits = v["hits"].as_array().expect("hits array");
+    assert!(!hits.is_empty(), "expected at least 1 hit");
+    for h in hits {
+        assert_eq!(h["score_kind"], "bm25");
+    }
+}
+
+#[test]
+fn old_wire_reader_compat_score_kind_optional_field() {
+    // The wire schema marks `score_kind` as additive (not required).
+    // We can't easily simulate an old reader from inside Rust, but we
+    // can confirm the JSON includes the field — old readers that
+    // ignore unknown fields are unaffected. This test just ensures
+    // the field is always present in fb-38+ output.
+    let dir = tempfile::tempdir().unwrap();
+    let (cfg, workspace, _data) = common::write_config(dir.path(), 0);
+    doc_with_term(&workspace);
+    common::ingest(&cfg, &workspace);
+
+    let (stdout, _stderr) = common::run_search_with_args(
+        &cfg,
+        &["--mode", "lexical", "--json", "rust"],
+    );
+    let v: Value = serde_json::from_str(stdout.trim()).unwrap();
+    let hit = &v["hits"][0];
+    assert!(hit.get("score_kind").is_some(), "score_kind always emitted");
+}

crates/kebab-cli/tests/wire_search_stale.rs

@@ -0,0 +1,106 @@
+//! p9-fb-32: CLI emits `indexed_at` + `stale` on JSON; plain output
+//! gains a `[stale]` tag prefix on stale hits.
+//!
+//! Self-contained: each test builds a TempDir workspace + config,
+//! invokes the `kebab` binary via `CARGO_BIN_EXE_kebab`, and (for the
+//! plain-output stale path) backdates `documents.updated_at` directly
+//! via `rusqlite` to simulate an aged-out doc without faking system
+//! time. Mirrors the helper pattern in
+//! `crates/kebab-app/tests/common/mod.rs::backdate_document_updated_at`.
+//!
+//! Shared TempDir / ingest / backdate helpers live in
+//! `tests/common/mod.rs`; see also `wire_ask_stale.rs`.
+
+mod common;
+
+use std::fs;
+use std::path::Path;
+use std::process::Command;
+
+fn run_search_lexical(cfg: &Path, query: &str, json: bool) -> std::process::Output {
+    let bin = env!("CARGO_BIN_EXE_kebab");
+    let mut cmd = Command::new(bin);
+    cmd.arg("--config").arg(cfg);
+    if json {
+        cmd.arg("--json");
+    }
+    // Force lexical so the test doesn't need fastembed / AVX. Hybrid
+    // is the CLI default which would try the vector path.
+    cmd.args(["search", "--mode", "lexical", query]);
+    let out = cmd.output().unwrap();
+    assert!(
+        out.status.success(),
+        "search failed: stderr={}",
+        String::from_utf8_lossy(&out.stderr)
+    );
+    out
+}
+
+#[test]
+fn search_json_includes_indexed_at_and_stale() {
+    let dir = tempfile::tempdir().unwrap();
+    let (cfg, workspace, _data) = common::write_config(dir.path(), 30);
+    fs::write(workspace.join("a.md"), "# Title\n\napples are fruit\n").unwrap();
+    common::ingest(&cfg, &workspace);
+
+    let out = run_search_lexical(&cfg, "apples", true);
+    let stdout = String::from_utf8_lossy(&out.stdout);
+    // p9-fb-34: top-level wire is now `search_response.v1` wrapping the
+    // legacy `search_hit.v1[]` under a `hits` field (with pagination +
+    // truncation metadata). Hit shape inside `hits` is unchanged.
+    let resp: serde_json::Value = serde_json::from_str(stdout.trim())
+        .unwrap_or_else(|e| panic!("expected JSON object, got {stdout:?}: {e}"));
+    assert_eq!(
+        resp.get("schema_version").and_then(|v| v.as_str()),
+        Some("search_response.v1"),
+        "expected search_response.v1 wrapper, got {resp}"
+    );
+    let arr = resp
+        .get("hits")
+        .and_then(|h| h.as_array())
+        .unwrap_or_else(|| panic!("expected hits array, got {stdout}"));
+    let first = arr.first().unwrap_or_else(|| panic!("expected ≥1 hit, got empty hits: {stdout}"));
+    assert!(
+        first.get("indexed_at").is_some(),
+        "missing indexed_at in {first}"
+    );
+    assert!(
+        first.get("stale").is_some(),
+        "missing stale in {first}"
+    );
+    assert_eq!(
+        first["stale"], false,
+        "freshly ingested doc must not be stale at default 30d threshold"
+    );
+}
+
+#[test]
+fn search_plain_marks_stale_doc() {
+    let dir = tempfile::tempdir().unwrap();
+    let (cfg, workspace, data) = common::write_config(dir.path(), 30);
+    fs::write(workspace.join("a.md"), "# Title\n\napples are fruit\n").unwrap();
+    common::ingest(&cfg, &workspace);
+    common::backdate_updated_at(&data, "a.md", 60);
+
+    let out = run_search_lexical(&cfg, "apples", false);
+    let stdout = String::from_utf8_lossy(&out.stdout);
+    assert!(
+        stdout.contains("[stale]"),
+        "stale tag missing in plain output:\n{stdout}"
+    );
+}
+
+#[test]
+fn search_plain_no_stale_tag_for_fresh_doc() {
+    let dir = tempfile::tempdir().unwrap();
+    let (cfg, workspace, _data) = common::write_config(dir.path(), 30);
+    fs::write(workspace.join("a.md"), "# Title\n\napples are fruit\n").unwrap();
+    common::ingest(&cfg, &workspace);
+
+    let out = run_search_lexical(&cfg, "apples", false);
+    let stdout = String::from_utf8_lossy(&out.stdout);
+    assert!(
+        !stdout.contains("[stale]"),
+        "unexpected stale tag in plain output for fresh doc:\n{stdout}"
+    );
+}

crates/kebab-cli/tests/wire_search_trace.rs

@@ -0,0 +1,58 @@
+//! p9-fb-37: integration tests for `kebab search --trace --json`.
+
+mod common;
+
+use serde_json::Value;
+use std::fs;
+
+#[test]
+fn search_trace_json_includes_trace_block() {
+    let dir = tempfile::tempdir().unwrap();
+    let (cfg, workspace, _data) = common::write_config(dir.path(), 0);
+    fs::write(workspace.join("doc1.md"), "# Title\n\nrust async hello\n").unwrap();
+    common::ingest(&cfg, &workspace);
+
+    let (stdout, _stderr) = common::run_search_with_args(
+        &cfg,
+        &["--mode", "lexical", "--trace", "--json", "rust"],
+    );
+    let v: Value = serde_json::from_str(stdout.trim()).expect("valid JSON");
+    assert_eq!(v["schema_version"], "search_response.v1");
+    assert!(v["trace"].is_object(), "trace block present");
+    assert!(v["trace"]["timing"].is_object());
+    assert!(v["trace"]["timing"]["total_ms"].is_number());
+    assert!(v["trace"]["lexical"].is_array());
+    assert!(v["trace"]["vector"].is_array());
+    assert!(v["trace"]["rrf_inputs"].is_array());
+}
+
+#[test]
+fn search_without_trace_omits_trace_field() {
+    let dir = tempfile::tempdir().unwrap();
+    let (cfg, workspace, _data) = common::write_config(dir.path(), 0);
+    fs::write(workspace.join("doc1.md"), "# Title\n\nrust async hello\n").unwrap();
+    common::ingest(&cfg, &workspace);
+
+    let (stdout, _stderr) = common::run_search_with_args(
+        &cfg,
+        &["--mode", "lexical", "--json", "rust"],
+    );
+    let v: Value = serde_json::from_str(stdout.trim()).expect("valid JSON");
+    assert!(v.get("trace").is_none(), "trace field absent without --trace");
+}
+
+#[test]
+fn search_trace_lexical_mode_vector_list_empty() {
+    let dir = tempfile::tempdir().unwrap();
+    let (cfg, workspace, _data) = common::write_config(dir.path(), 0);
+    fs::write(workspace.join("doc1.md"), "# Title\n\nrust async hello\n").unwrap();
+    common::ingest(&cfg, &workspace);
+
+    let (stdout, _stderr) = common::run_search_with_args(
+        &cfg,
+        &["--mode", "lexical", "--trace", "--json", "rust"],
+    );
+    let v: Value = serde_json::from_str(stdout.trim()).expect("valid JSON");
+    assert_eq!(v["trace"]["vector"].as_array().unwrap().len(), 0);
+    assert_eq!(v["trace"]["timing"]["vector_ms"], 0);
+}

crates/kebab-config/src/lib.rs

@@ -45,6 +45,11 @@ pub struct Config {
     /// `dark`).
     #[serde(default = "UiCfg::defaults")]
     pub ui: UiCfg,
+    /// p10-1A-1: code ingest settings. `#[serde(default)]` so existing
+    /// config files without an `[ingest]` / `[ingest.code]` section
+    /// load cleanly with built-in defaults.
+    #[serde(default)]
+    pub ingest: IngestCfg,
     /// p9-fb-05: directory of the on-disk config file this `Config`
     /// was loaded from, if any. Populated by `Config::from_file` /
     /// `Config::load` — never serialized (`#[serde(skip)]`). Used by
@@ -131,12 +136,21 @@ pub struct SearchCfg {
     /// (corpus_revision mismatch) are evicted on next access.
     #[serde(default = "default_cache_capacity")]
     pub cache_capacity: usize,
+    /// p9-fb-32: hits and citations whose source doc was last
+    /// re-processed more than this many days ago are marked
+    /// `stale: true` in wire / TUI / CLI surfaces. `0` disables.
+    #[serde(default = "default_stale_threshold_days")]
+    pub stale_threshold_days: u32,
 }
 
 fn default_cache_capacity() -> usize {
     256
 }
 
+fn default_stale_threshold_days() -> u32 {
+    30
+}
+
 #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
 pub struct RagCfg {
     pub prompt_template_version: String,
@@ -256,6 +270,52 @@ impl UiCfg {
     }
 }
 
+/// p10-1A-1: top-level ingest configuration wrapper. Contains per-media-type
+/// sub-sections; currently only `code` is defined.
+#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
+#[serde(default)]
+pub struct IngestCfg {
+    pub code: IngestCodeCfg,
+}
+
+/// p10-1A-1: settings for the code ingest pipeline. All fields have
+/// reasonable defaults so the user need not set anything in `config.toml`
+/// to get working code ingest.
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+#[serde(default)]
+pub struct IngestCodeCfg {
+    /// Generated header sniff. Reads first ~512 bytes, checks 7 markers.
+    pub skip_generated_header: bool,
+    /// Max byte size per file. Bigger files skipped.
+    pub max_file_bytes: u64,
+    /// Max line count per file. Bigger files skipped (byte cap checked first).
+    pub max_file_lines: u32,
+    /// User extra skip globs (gitignore syntax). Applied on top of built-in
+    /// + `.gitignore` + `.kebabignore`.
+    pub extra_skip_globs: Vec<String>,
+    /// AST chunk size cap. Functions/classes longer than this fall back to
+    /// paragraph-based split (1A-2 and later).
+    pub ast_chunk_max_lines: u32,
+    /// Tier 3 fallback chunker: lines per chunk.
+    pub fallback_lines_per_chunk: u32,
+    /// Tier 3 fallback chunker: line overlap between adjacent chunks.
+    pub fallback_lines_overlap: u32,
+}
+
+impl Default for IngestCodeCfg {
+    fn default() -> Self {
+        Self {
+            skip_generated_header: true,
+            max_file_bytes: 262_144,
+            max_file_lines: 5_000,
+            extra_skip_globs: vec![],
+            ast_chunk_max_lines: 200,
+            fallback_lines_per_chunk: 80,
+            fallback_lines_overlap: 20,
+        }
+    }
+}
+
 impl Config {
     /// Defaults per design §6.4.
     pub fn defaults() -> Self {
@@ -293,9 +353,9 @@ impl Config {
             models: ModelsCfg {
                 embedding: EmbeddingModelCfg {
                     provider: "fastembed".to_string(),
-                    model: "multilingual-e5-small".to_string(),
+                    model: "multilingual-e5-large".to_string(),
                     version: "v1".to_string(),
-                    dimensions: 384,
+                    dimensions: 1024,
                     batch_size: 64,
                 },
                 llm: LlmCfg {
@@ -317,15 +377,17 @@ impl Config {
                 rrf_k: 60,
                 snippet_chars: 220,
                 cache_capacity: default_cache_capacity(),
+                stale_threshold_days: 30,
             },
             rag: RagCfg {
-                prompt_template_version: "rag-v1".to_string(),
+                prompt_template_version: "rag-v2".to_string(),
                 score_gate: 0.30,
                 explain_default: false,
                 max_context_tokens: 8000,
             },
             image: ImageCfg::defaults(),
             ui: UiCfg::defaults(),
+            ingest: IngestCfg::default(),
             // p9-fb-05: defaults are not loaded from disk, so no
             // source_dir. Relative `workspace.root` (rare with
             // defaults) falls back to caller `cwd` via the
@@ -393,6 +455,25 @@ impl Config {
                 if p.exists() {
                     Self::from_file(&p)?
                 } else {
+                    // macOS migration: if the new XDG path is absent but the
+                    // old ~/Library/Application Support/kebab/config.toml exists,
+                    // copy it to the new location so the user doesn't lose settings.
+                    if let Some(legacy) = Self::macos_legacy_config_path() {
+                        if legacy.exists() && !p.exists() {
+                            if let Some(parent) = p.parent() {
+                                let _ = std::fs::create_dir_all(parent);
+                            }
+                            if std::fs::copy(&legacy, &p).is_ok() {
+                                eprintln!(
+                                    "kebab: migrated config {} → {}",
+                                    legacy.display(),
+                                    p.display()
+                                );
+                                return Self::from_file(&p)
+                                    .map(|c| c.apply_env(&std::env::vars().collect()));
+                            }
+                        }
+                    }
                     Self::defaults()
                 }
             }
@@ -558,6 +639,11 @@ impl Config {
                         self.search.snippet_chars = n;
                     }
                 }
+                "KEBAB_SEARCH_STALE_THRESHOLD_DAYS" => {
+                    if let Ok(n) = v.parse::<u32>() {
+                        self.search.stale_threshold_days = n;
+                    }
+                }
 
                 // rag
                 "KEBAB_RAG_PROMPT_TEMPLATE_VERSION" => {
@@ -634,8 +720,11 @@ impl Config {
                 return PathBuf::from(custom).join("kebab").join("config.toml");
             }
         }
-        match dirs::config_dir() {
-            Some(d) => d.join("kebab").join("config.toml"),
+        // Always use XDG-standard ~/.config regardless of platform.
+        // macOS dirs::config_dir() returns ~/Library/Application Support which
+        // collides with data_dir() — DataOnly reset would delete config too.
+        match dirs::home_dir() {
+            Some(h) => h.join(".config").join("kebab").join("config.toml"),
             None => PathBuf::from("./kebab/config.toml"),
         }
     }
@@ -647,8 +736,9 @@ impl Config {
                 return PathBuf::from(custom).join("kebab");
             }
         }
-        match dirs::data_dir() {
-            Some(d) => d.join("kebab"),
+        // Always use XDG-standard ~/.local/share regardless of platform.
+        match dirs::home_dir() {
+            Some(h) => h.join(".local").join("share").join("kebab"),
             None => PathBuf::from("./kebab-data"),
         }
     }
@@ -660,8 +750,9 @@ impl Config {
                 return PathBuf::from(custom).join("kebab");
             }
         }
-        match dirs::cache_dir() {
-            Some(d) => d.join("kebab"),
+        // Always use XDG-standard ~/.cache regardless of platform.
+        match dirs::home_dir() {
+            Some(h) => h.join(".cache").join("kebab"),
             None => PathBuf::from("./kebab-cache"),
         }
     }
@@ -680,6 +771,25 @@ impl Config {
         }
         PathBuf::from("./kebab-state")
     }
+
+    /// macOS legacy config path: `~/Library/Application Support/kebab/config.toml`.
+    /// Returns `None` on non-macOS or when home dir is unavailable.
+    /// Used for one-time migration to the XDG-standard location.
+    fn macos_legacy_config_path() -> Option<PathBuf> {
+        #[cfg(target_os = "macos")]
+        {
+            dirs::home_dir().map(|h| {
+                h.join("Library")
+                    .join("Application Support")
+                    .join("kebab")
+                    .join("config.toml")
+            })
+        }
+        #[cfg(not(target_os = "macos"))]
+        {
+            None
+        }
+    }
 }
 
 /// Parse a permissive boolean — `1` / `true` / `yes` (case-insensitive)
@@ -706,10 +816,17 @@ mod tests {
         let c = Config::defaults();
         assert_eq!(c.rag.score_gate, 0.30);
         assert_eq!(c.chunking.target_tokens, 500);
-        assert_eq!(c.models.embedding.dimensions, 384);
+        assert_eq!(c.models.embedding.model, "multilingual-e5-large");
+        assert_eq!(c.models.embedding.dimensions, 1024);
         assert_eq!(c.search.rrf_k, 60);
     }
 
+    #[test]
+    fn defaults_rag_prompt_template_version_is_rag_v2() {
+        let c = Config::defaults();
+        assert_eq!(c.rag.prompt_template_version, "rag-v2");
+    }
+
     #[test]
     fn env_override_score_gate() {
         let mut env = HashMap::new();
@@ -883,9 +1000,9 @@ chunker_version = "md-heading-v1"
 
 [models.embedding]
 provider = "fastembed"
-model = "multilingual-e5-small"
+model = "multilingual-e5-large"
 version = "v1"
-dimensions = 384
+dimensions = 1024
 batch_size = 64
 
 [models.llm]
@@ -901,9 +1018,10 @@ default_k = 10
 hybrid_fusion = "rrf"
 rrf_k = 60
 snippet_chars = 220
+stale_threshold_days = 30
 
 [rag]
-prompt_template_version = "rag-v1"
+prompt_template_version = "rag-v2"
 score_gate = 0.30
 explain_default = false
 max_context_tokens = 8000
@@ -938,6 +1056,44 @@ max_context_tokens = 8000
         let WorkspaceCfg { root: _, exclude: _ } = &ws;
     }
 
+    #[test]
+    fn default_stale_threshold_is_30() {
+        let c = Config::defaults();
+        assert_eq!(c.search.stale_threshold_days, 30);
+    }
+
+    #[test]
+    fn env_override_stale_threshold() {
+        let c = Config::defaults();
+        let env: HashMap<String, String> = [
+            ("KEBAB_SEARCH_STALE_THRESHOLD_DAYS".to_string(), "7".to_string()),
+        ]
+        .into_iter()
+        .collect();
+        let c = c.apply_env(&env);
+        assert_eq!(c.search.stale_threshold_days, 7);
+    }
+
+    #[test]
+    fn env_negative_threshold_silently_ignored() {
+        // Env path: malformed numeric values (including negatives that
+        // can't fit `u32`) are silently ignored — same pattern as
+        // `KEBAB_SEARCH_DEFAULT_K`. The TOML file-load path (covered in
+        // `fb27_tests::file_negative_stale_threshold_returns_config_invalid`)
+        // is the spec-required hard error surface.
+        let c = Config::defaults();
+        let env: HashMap<String, String> = [
+            ("KEBAB_SEARCH_STALE_THRESHOLD_DAYS".to_string(), "-5".to_string()),
+        ]
+        .into_iter()
+        .collect();
+        let c = c.apply_env(&env);
+        assert_eq!(
+            c.search.stale_threshold_days, 30,
+            "env path: malformed value must leave the default unchanged"
+        );
+    }
+
     #[test]
     fn xdg_paths_honor_env() {
         // Must restore env after the test to avoid polluting other tests.
@@ -956,6 +1112,49 @@ max_context_tokens = 8000
             }
         }
     }
+
+    #[test]
+    fn ingest_code_cfg_defaults() {
+        let cfg: IngestCodeCfg = toml::from_str("").unwrap();
+        assert_eq!(cfg.max_file_bytes, 262_144);
+        assert_eq!(cfg.max_file_lines, 5_000);
+        assert!(cfg.skip_generated_header);
+        assert!(cfg.extra_skip_globs.is_empty());
+        assert_eq!(cfg.ast_chunk_max_lines, 200);
+        assert_eq!(cfg.fallback_lines_per_chunk, 80);
+        assert_eq!(cfg.fallback_lines_overlap, 20);
+    }
+
+    #[test]
+    fn ingest_code_cfg_user_override() {
+        let toml = r#"
+            max_file_bytes = 1048576
+            max_file_lines = 20000
+            skip_generated_header = false
+            extra_skip_globs = ["**/fixtures/**", "**/snapshots/**"]
+        "#;
+        let cfg: IngestCodeCfg = toml::from_str(toml).unwrap();
+        assert_eq!(cfg.max_file_bytes, 1_048_576);
+        assert_eq!(cfg.max_file_lines, 20_000);
+        assert!(!cfg.skip_generated_header);
+        assert_eq!(cfg.extra_skip_globs.len(), 2);
+    }
+
+    #[test]
+    fn config_with_ingest_code_section() {
+        // Build a full valid Config serialization and patch only the
+        // [ingest.code] field we care about — avoids having to enumerate
+        // every required Config field in the test fixture.
+        let base = Config::defaults();
+        let mut toml_text = toml::to_string(&base).unwrap();
+        // Inject max_file_bytes override into the [ingest.code] table.
+        toml_text = toml_text.replace(
+            "max_file_bytes = 262144",
+            "max_file_bytes = 524288",
+        );
+        let cfg: Config = toml::from_str(&toml_text).unwrap();
+        assert_eq!(cfg.ingest.code.max_file_bytes, 524_288);
+    }
 }
 
 #[cfg(test)]
@@ -984,4 +1183,38 @@ mod fb27_tests {
         assert_eq!(signal.path, p);
         assert!(!signal.cause.is_empty(), "cause should be non-empty");
     }
+
+    /// Spec §Config: a negative `stale_threshold_days` in TOML must be
+    /// rejected at load time (not silently coerced or ignored). serde's
+    /// `u32` type-check surfaces the failure as a parse error, which
+    /// `from_file` wraps into `ConfigInvalid`. CLI's `error_classify`
+    /// downcasts this and emits `error.v1.code = "config_invalid"`.
+    #[test]
+    fn file_negative_stale_threshold_returns_config_invalid() {
+        let dir = tempfile::tempdir().unwrap();
+        let p = dir.path().join("neg.toml");
+        // Build a minimally valid TOML and override only the field
+        // under test — this isolates the failure to the negative
+        // value rather than missing required sections.
+        let cfg = Config::defaults();
+        let mut toml_text = toml::to_string(&cfg).expect("default round-trips");
+        assert!(
+            toml_text.contains("stale_threshold_days = 30"),
+            "default value drifted; update test fixture"
+        );
+        toml_text = toml_text.replace(
+            "stale_threshold_days = 30",
+            "stale_threshold_days = -5",
+        );
+        std::fs::write(&p, &toml_text).unwrap();
+        let err = Config::from_file(&p).unwrap_err();
+        let signal = err.downcast_ref::<ConfigInvalid>()
+            .expect("negative stale_threshold_days should downcast to ConfigInvalid");
+        assert_eq!(signal.path, p);
+        assert!(
+            signal.cause.contains("parse_failed"),
+            "expected parse_failed cause, got: {}",
+            signal.cause
+        );
+    }
 }

crates/kebab-core/src/answer.rs

@@ -35,6 +35,11 @@ pub struct Answer {
 pub struct AnswerCitation {
     pub marker: Option<String>,
     pub citation: Citation,
+    /// p9-fb-32: cited doc's `documents.updated_at`.
+    #[serde(with = "time::serde::rfc3339")]
+    pub indexed_at: OffsetDateTime,
+    /// p9-fb-32: server-computed staleness flag per config threshold.
+    pub stale: bool,
 }
 
 /// p9-fb-15: history 가 prompt 에 들어갈 때의 한 turn. RAG facade 가
@@ -90,3 +95,29 @@ pub struct TokenUsage {
 
 #[derive(Clone, Debug, Eq, Hash, PartialEq, Serialize, Deserialize)]
 pub struct TraceId(pub String);
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::asset::WorkspacePath;
+    use crate::citation::Citation;
+    use time::macros::datetime;
+
+    #[test]
+    fn answer_citation_serializes_indexed_at_and_stale() {
+        let ac = AnswerCitation {
+            marker: Some("[1]".to_string()),
+            citation: Citation::Line {
+                path: WorkspacePath::new("a.md".to_string()).unwrap(),
+                start: 1,
+                end: 1,
+                section: None,
+            },
+            indexed_at: datetime!(2026-05-09 12:00:00 UTC),
+            stale: false,
+        };
+        let v = serde_json::to_value(&ac).unwrap();
+        assert_eq!(v["indexed_at"], "2026-05-09T12:00:00Z");
+        assert_eq!(v["stale"], false);
+    }
+}

crates/kebab-core/src/citation.rs

@@ -37,6 +37,13 @@ pub enum Citation {
         end_ms: u64,
         speaker: Option<String>,
     },
+    Code {
+        path: WorkspacePath,
+        line_start: u32,
+        line_end: u32,
+        symbol: Option<String>,
+        lang: Option<String>,
+    },
 }
 
 impl Citation {
@@ -46,7 +53,8 @@ impl Citation {
             | Citation::Page { path, .. }
             | Citation::Region { path, .. }
             | Citation::Caption { path, .. }
-            | Citation::Time { path, .. } => path,
+            | Citation::Time { path, .. }
+            | Citation::Code { path, .. } => path,
         }
     }
 
@@ -80,6 +88,18 @@ impl Citation {
                     None => format!("{}#t={},{}", path.0, s, e),
                 }
             }
+            Citation::Code {
+                path,
+                line_start,
+                line_end,
+                ..
+            } => {
+                if line_start == line_end {
+                    format!("{}#L{}", path.0, line_start)
+                } else {
+                    format!("{}#L{}-L{}", path.0, line_start, line_end)
+                }
+            }
         }
     }
 
@@ -354,4 +374,64 @@ mod tests {
         let r = Citation::parse("notes/x#evil.md#L7");
         assert!(r.is_err(), "path with embedded '#' must be rejected");
     }
+
+    #[test]
+    fn citation_code_variant_serializes_with_kind_tag() {
+        let c = Citation::Code {
+            path: WorkspacePath("crates/kebab-chunk/src/md_heading_v1.rs".into()),
+            line_start: 142,
+            line_end: 168,
+            symbol: Some("MdHeadingV1Chunker::chunk_doc".into()),
+            lang: Some("rust".into()),
+        };
+        let v = serde_json::to_value(&c).unwrap();
+        assert_eq!(v["kind"], "code");
+        assert_eq!(v["line_start"], 142);
+        assert_eq!(v["line_end"], 168);
+        assert_eq!(v["symbol"], "MdHeadingV1Chunker::chunk_doc");
+        assert_eq!(v["lang"], "rust");
+        // Existing 5 variants must NOT pick up these fields.
+        let line = Citation::Line {
+            path: WorkspacePath("notes/foo.md".into()),
+            start: 1,
+            end: 10,
+            section: None,
+        };
+        let lv = serde_json::to_value(&line).unwrap();
+        assert!(lv.get("line_start").is_none());
+        assert!(lv.get("symbol").is_none());
+    }
+
+    #[test]
+    fn citation_code_uri_format() {
+        let c = Citation::Code {
+            path: WorkspacePath("a/b.rs".into()),
+            line_start: 10,
+            line_end: 20,
+            symbol: None,
+            lang: Some("rust".into()),
+        };
+        assert_eq!(c.to_uri(), "a/b.rs#L10-L20");
+        // Single-line uses `#L10`.
+        let single = Citation::Code {
+            path: WorkspacePath("a/b.rs".into()),
+            line_start: 5,
+            line_end: 5,
+            symbol: None,
+            lang: None,
+        };
+        assert_eq!(single.to_uri(), "a/b.rs#L5");
+    }
+
+    #[test]
+    fn citation_code_path_accessor() {
+        let c = Citation::Code {
+            path: WorkspacePath("x.rs".into()),
+            line_start: 1,
+            line_end: 1,
+            symbol: None,
+            lang: None,
+        };
+        assert_eq!(c.path().0, "x.rs");
+    }
 }

crates/kebab-core/src/document.rs

@@ -142,6 +142,18 @@ pub enum SourceSpan {
         start_ms: u64,
         end_ms: u64,
     },
+    /// p10-1A-2: AST-unit span for code ingest. Internal storage shape
+    /// (chunks.source_spans_json) — `citation_helper` maps this to the
+    /// wire `Citation::Code` (added 1A-1). `symbol` is the per-language
+    /// self-reference path (design §3.4); `<top-level>` / `<module>` for
+    /// glue regions, never null for an identified unit. `lang` is the
+    /// canonical code_lang.
+    Code {
+        line_start: u32,
+        line_end: u32,
+        symbol: Option<String>,
+        lang: Option<String>,
+    },
 }
 
 // ── Forward-declared stubs (§3.7a). Bodies are final per design. ────────
@@ -195,6 +207,24 @@ mod tests {
     /// previously failed at serde runtime because `tag = "kind"` cannot
     /// describe a newtype carrying a non-struct value. The struct-variant
     /// shape used here is the §9 schema migration.
+    #[test]
+    fn source_span_code_round_trips_and_tags_lowercase() {
+        let s = SourceSpan::Code {
+            line_start: 10,
+            line_end: 42,
+            symbol: Some("foo::Bar::baz".to_string()),
+            lang: Some("rust".to_string()),
+        };
+        let v = serde_json::to_value(&s).unwrap();
+        assert_eq!(v["kind"], "code");
+        assert_eq!(v["line_start"], 10);
+        assert_eq!(v["line_end"], 42);
+        assert_eq!(v["symbol"], "foo::Bar::baz");
+        assert_eq!(v["lang"], "rust");
+        let back: SourceSpan = serde_json::from_value(v).unwrap();
+        assert_eq!(back, s);
+    }
+
     #[test]
     fn inline_serde_round_trip() {
         let cases = vec![

crates/kebab-core/src/fetch.rs

@@ -0,0 +1,87 @@
+//! p9-fb-35 verbatim fetch domain types.
+//!
+//! Three modes (chunk / doc / span) carried by [`FetchQuery`]; one
+//! response shape ([`FetchResult`]) discriminated by [`FetchKind`].
+//! All types are `Serialize` so the CLI / MCP wire layers can hand
+//! them straight through `serde_json::to_value`.
+
+use serde::{Deserialize, Serialize};
+use time::OffsetDateTime;
+
+use crate::asset::WorkspacePath;
+use crate::chunk::Chunk;
+use crate::ids::{ChunkId, DocumentId};
+
+#[derive(Clone, Debug)]
+pub enum FetchQuery {
+    Chunk(ChunkId),
+    Doc(DocumentId),
+    Span {
+        doc_id: DocumentId,
+        line_start: u32,
+        line_end: u32,
+    },
+}
+
+#[derive(Clone, Debug, Default)]
+pub struct FetchOpts {
+    /// chunk mode only: ±N chunks. None = no surrounding context.
+    pub context: Option<u32>,
+    /// doc / span mode only: chars/4 budget. None = no cap.
+    pub max_tokens: Option<usize>,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum FetchKind {
+    Chunk,
+    Doc,
+    Span,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct FetchResult {
+    pub kind: FetchKind,
+    pub doc_id: DocumentId,
+    pub doc_path: WorkspacePath,
+    #[serde(with = "time::serde::rfc3339")]
+    pub indexed_at: OffsetDateTime,
+    pub stale: bool,
+    // chunk mode payloads
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub chunk: Option<Chunk>,
+    #[serde(skip_serializing_if = "Vec::is_empty", default)]
+    pub context_before: Vec<Chunk>,
+    #[serde(skip_serializing_if = "Vec::is_empty", default)]
+    pub context_after: Vec<Chunk>,
+    // doc / span payloads
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub text: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub line_start: Option<u32>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub line_end: Option<u32>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub effective_end: Option<u32>,
+    pub truncated: bool,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn fetch_opts_default_is_all_none() {
+        let o = FetchOpts::default();
+        assert!(o.context.is_none());
+        assert!(o.max_tokens.is_none());
+    }
+
+    #[test]
+    fn fetch_kind_serializes_snake_case() {
+        let v = serde_json::to_value(FetchKind::Chunk).unwrap();
+        assert_eq!(v, serde_json::json!("chunk"));
+        let v = serde_json::to_value(FetchKind::Span).unwrap();
+        assert_eq!(v, serde_json::json!("span"));
+    }
+}

crates/kebab-core/src/ingest.rs

@@ -25,10 +25,52 @@ pub struct IngestReport {
     /// extension key under "<no-ext>". `BTreeMap` so the wire JSON
     /// has stable key order across runs.
     pub skipped_by_extension: std::collections::BTreeMap<String, u32>,
+    /// p10-1A-1: files skipped because they matched a repo-local `.gitignore`.
+    #[serde(default)]
+    pub skipped_gitignore: u32,
+    /// p10-1A-1: files skipped because they matched a `.kebabignore` entry.
+    #[serde(default)]
+    pub skipped_kebabignore: u32,
+    /// p10-1A-1: files skipped because they matched the built-in safety-net
+    /// blacklist (`node_modules/`, `target/`, `__pycache__/`, `.venv/`,
+    /// `venv/`, `env/`).
+    #[serde(default)]
+    pub skipped_builtin_blacklist: u32,
+    /// p10-1A-1: files skipped because their first ~512 bytes contained a
+    /// generated-file marker (`@generated`, `do not edit`, …).
+    #[serde(default)]
+    pub skipped_generated: u32,
+    /// p10-1A-1: files skipped because they exceeded `max_file_bytes` or
+    /// `max_file_lines` in `[ingest.code]`.
+    #[serde(default)]
+    pub skipped_size_exceeded: u32,
+    /// p10-1A-1: sample file paths per skip category (≤ 5 each).
+    #[serde(default)]
+    pub skip_examples: SkipExamples,
+    /// Dogfood: docs whose on-disk file was deleted since the last ingest
+    /// and were therefore removed from the store. Additive field — older
+    /// wire consumers that pre-date this field read it as 0 via
+    /// `#[serde(default)]`.
+    #[serde(default)]
+    pub purged_deleted_files: u32,
     /// `None` ↔ wire `items: null` (`--summary-only`).
     pub items: Option<Vec<IngestItem>>,
 }
 
+/// p10-1A-1: per-category sample of skipped file paths. Each category caps at
+/// 5 entries (oldest-first). Used for debugging "why was X not indexed?"
+#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
+pub struct SkipExamples {
+    #[serde(default)]
+    pub generated: Vec<String>,
+    #[serde(default)]
+    pub size_exceeded: Vec<String>,
+    #[serde(default)]
+    pub builtin_blacklist: Vec<String>,
+    #[serde(default)]
+    pub gitignore: Vec<String>,
+}
+
 #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
 pub struct IngestItem {
     pub kind: IngestItemKind,
@@ -58,3 +100,56 @@ pub enum IngestItemKind {
     Unchanged,
     Error,
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::traits::SourceScope;
+
+    #[test]
+    fn skip_examples_default_is_empty() {
+        let s = SkipExamples::default();
+        assert!(s.generated.is_empty());
+        assert!(s.size_exceeded.is_empty());
+        assert!(s.builtin_blacklist.is_empty());
+        assert!(s.gitignore.is_empty());
+    }
+
+    #[test]
+    fn ingest_report_skip_counters_serialize() {
+        let r = IngestReport {
+            scope: SourceScope {
+                root: std::path::PathBuf::from("/tmp"),
+                include: vec![],
+                exclude: vec![],
+            },
+            scanned: 100,
+            new: 50,
+            updated: 0,
+            skipped: 0,
+            unchanged: 0,
+            errors: 0,
+            duration_ms: 1234,
+            skipped_by_extension: Default::default(),
+            skipped_gitignore: 30,
+            skipped_kebabignore: 5,
+            skipped_builtin_blacklist: 10,
+            skipped_generated: 3,
+            skipped_size_exceeded: 2,
+            skip_examples: SkipExamples {
+                generated: vec!["a/b.pb.rs".into()],
+                size_exceeded: vec![],
+                builtin_blacklist: vec!["node_modules/x.js".into()],
+                gitignore: vec![],
+            },
+            purged_deleted_files: 0,
+            items: None,
+        };
+        let v = serde_json::to_value(&r).unwrap();
+        assert_eq!(v["skipped_gitignore"], 30);
+        assert_eq!(v["skipped_builtin_blacklist"], 10);
+        assert_eq!(v["skipped_generated"], 3);
+        assert_eq!(v["skipped_size_exceeded"], 2);
+        assert_eq!(v["skip_examples"]["generated"][0], "a/b.pb.rs");
+    }
+}

crates/kebab-core/src/lib.rs

@@ -23,6 +23,7 @@ pub mod vector;
 pub mod errors;
 pub mod traits;
 pub mod normalize;
+pub mod fetch;
 
 // Re-export the most commonly used items at the crate root, mirroring the
 // public surface listed in the task spec.
@@ -50,14 +51,15 @@ pub use metadata::{
     TrustLevel,
 };
 pub use search::{
-    DocFilter, DocSummary, RetrievalDetail, SearchFilters, SearchHit,
-    SearchMode, SearchQuery,
+    BulkSearchItem, BulkSearchResponse, BulkSearchSummary, DocFilter, DocSummary, IndexBytes, MEDIA_KINDS,
+    RetrievalDetail, ScoreKind, SearchFilters, SearchHit, SearchMode, SearchOpts, SearchQuery, SearchTrace,
+    TraceCandidate, TraceFusionInput, TraceTiming,
 };
 pub use answer::{
     Answer, AnswerCitation, AnswerRetrievalSummary, ModelRef, RefusalReason, TokenUsage,
     TraceId, Turn,
 };
-pub use ingest::{IngestItem, IngestItemKind, IngestReport};
+pub use ingest::{IngestItem, IngestItemKind, IngestReport, SkipExamples};
 pub use jobs::{JobFilter, JobId, JobKind, JobRow, JobStatus};
 pub use vector::{VectorHit, VectorRecord};
 pub use errors::CoreError;
@@ -68,3 +70,4 @@ pub use traits::{
     SourceScope, TokenChunk, VectorStore,
 };
 pub use normalize::{nfc, to_posix};
+pub use fetch::{FetchKind, FetchOpts, FetchQuery, FetchResult};

crates/kebab-core/src/media.rs

@@ -40,5 +40,23 @@ pub enum MediaType {
     Pdf,
     Image(ImageType),
     Audio(AudioType),
+    /// p10-1A-2: a source-code file. Inner string is the canonical
+    /// code_lang (design §3.5). 1A activates `"rust"` only; other
+    /// recognized code langs are still routed `Other` until their phase.
+    Code(String),
     Other(String),
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn media_type_code_serializes_lowercase_tagged() {
+        let m = MediaType::Code("rust".to_string());
+        let v = serde_json::to_value(&m).unwrap();
+        assert_eq!(v, serde_json::json!({ "code": "rust" }));
+        let back: MediaType = serde_json::from_value(v).unwrap();
+        assert_eq!(back, m);
+    }
+}

crates/kebab-core/src/metadata.rs

@@ -17,6 +17,25 @@ pub struct Metadata {
     pub user_id_alias: Option<String>,
     /// Frontmatter keys we don't recognise are preserved here per §0 Q9.
     pub user: Map<String, Value>,
+
+    /// p10-1A-1: name of the source repo if the file lives inside a git
+    /// working tree (`.git/` walk-up). null otherwise.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub repo: Option<String>,
+
+    /// p10-1A-1: HEAD branch at ingest time. null when no repo or detached HEAD.
+    /// Informational only — current-state observability, not a partition key.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub git_branch: Option<String>,
+
+    /// p10-1A-1: HEAD commit (40-hex) at ingest time. null when no repo.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub git_commit: Option<String>,
+
+    /// p10-1A-1: programming language identifier (lowercase canonical). null
+    /// for markdown / pdf / image. Set by `kebab_parse_code::lang::code_lang_for_path`.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub code_lang: Option<String>,
 }
 
 #[derive(Clone, Copy, Debug, Eq, Hash, PartialEq, Serialize, Deserialize)]
@@ -66,3 +85,54 @@ pub enum ProvenanceKind {
     Warning,
     Error,
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn metadata_repo_fields_default_to_none_and_omit_when_serialized() {
+        let m = Metadata {
+            aliases: vec![],
+            tags: vec![],
+            created_at: time::OffsetDateTime::UNIX_EPOCH,
+            updated_at: time::OffsetDateTime::UNIX_EPOCH,
+            source_type: SourceType::Markdown,
+            trust_level: TrustLevel::Primary,
+            user_id_alias: None,
+            user: Default::default(),
+            repo: None,
+            git_branch: None,
+            git_commit: None,
+            code_lang: None,
+        };
+        let v = serde_json::to_value(&m).unwrap();
+        assert!(v.get("repo").is_none());
+        assert!(v.get("git_branch").is_none());
+        assert!(v.get("git_commit").is_none());
+        assert!(v.get("code_lang").is_none());
+    }
+
+    #[test]
+    fn metadata_repo_fields_present_when_some() {
+        let m = Metadata {
+            aliases: vec![],
+            tags: vec![],
+            created_at: time::OffsetDateTime::UNIX_EPOCH,
+            updated_at: time::OffsetDateTime::UNIX_EPOCH,
+            source_type: SourceType::Markdown,
+            trust_level: TrustLevel::Primary,
+            user_id_alias: None,
+            user: Default::default(),
+            repo: Some("kebab".into()),
+            git_branch: Some("main".into()),
+            git_commit: Some("a".repeat(40)),
+            code_lang: Some("rust".into()),
+        };
+        let v = serde_json::to_value(&m).unwrap();
+        assert_eq!(v["repo"], "kebab");
+        assert_eq!(v["git_branch"], "main");
+        assert_eq!(v["git_commit"].as_str().unwrap().len(), 40);
+        assert_eq!(v["code_lang"], "rust");
+    }
+}

crates/kebab-core/src/search.rs

@@ -26,12 +26,49 @@ pub struct SearchQuery {
     pub filters: SearchFilters,
 }
 
+/// p9-fb-36: canonical kind labels for `SearchFilters.media`. Mirrors
+/// `MediaType` variant tags; CLI / MCP normalize aliases (`md` → `markdown`)
+/// before populating this Vec.
+pub const MEDIA_KINDS: &[&str] = &["markdown", "pdf", "image", "audio", "other"];
+
+/// p9-fb-38: top-level `SearchHit.score` declaration.
+/// `Rrf` (hybrid) / `Bm25` (lexical-only) / `Cosine` (vector-only).
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum ScoreKind {
+    #[default]
+    Rrf,
+    Bm25,
+    Cosine,
+}
+
 #[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
 pub struct SearchFilters {
     pub tags_any: Vec<String>,
     pub lang: Option<Lang>,
     pub path_glob: Option<String>,
     pub trust_min: Option<TrustLevel>,
+    /// p9-fb-36: media_type filter — IN-list of `MediaType.kind`
+    /// strings (`"markdown"`, `"pdf"`, `"image"`, `"audio"`, `"other"`).
+    /// Empty Vec = no filter. Match is on the variant tag only;
+    /// e.g. `["image"]` matches `Image(Png)` and `Image(Jpeg)`.
+    #[serde(default)]
+    pub media: Vec<String>,
+    /// p9-fb-36: hits whose source doc's `documents.updated_at` is at
+    /// or after this timestamp. None = no filter. RFC3339 / UTC.
+    #[serde(default, with = "time::serde::rfc3339::option")]
+    pub ingested_after: Option<OffsetDateTime>,
+    /// p9-fb-36: restrict hits to a single document. None = no filter.
+    #[serde(default)]
+    pub doc_id: Option<DocumentId>,
+    /// p10-1A-1: filter by `metadata.repo`. Empty = no filter; multi-value = OR.
+    #[serde(default)]
+    pub repo: Vec<String>,
+    /// p10-1A-1: filter by `metadata.code_lang`. Empty = no filter; multi-value = OR.
+    /// Identifiers are lowercase canonical names (`rust`, `python`, `typescript`, ...).
+    /// Unknown values produce empty hits (consistent with `media` policy).
+    #[serde(default)]
+    pub code_lang: Vec<String>,
 }
 
 #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
@@ -48,6 +85,27 @@ pub struct SearchHit {
     pub index_version: IndexVersion,
     pub embedding_model: Option<EmbeddingModelId>,
     pub chunker_version: ChunkerVersion,
+    /// p9-fb-32: source doc's `documents.updated_at` (last actual re-process).
+    /// fb-23 incremental ingest skip path leaves this unchanged.
+    #[serde(with = "time::serde::rfc3339")]
+    pub indexed_at: OffsetDateTime,
+    /// p9-fb-32: server-computed `now - indexed_at > threshold` per
+    /// `config.search.stale_threshold_days`. `false` when threshold = 0.
+    pub stale: bool,
+    /// p9-fb-38: declares the meaning of the top-level `score`.
+    /// `Rrf` (hybrid mode), `Bm25` (lexical-only), `Cosine` (vector-only).
+    /// 옛 wire (fb-38 미만) 부재 시 `Rrf` default — hybrid 가 기본 mode.
+    #[serde(default)]
+    pub score_kind: ScoreKind,
+    /// p10-1A-1: optional. Filled when the source file lives in a git repo
+    /// (`.git/` walk-up). null for markdown / pdf / image hits and for code
+    /// hits ingested via `kebab ingest-file` outside a repo boundary.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub repo: Option<String>,
+    /// p10-1A-1: optional. Programming language identifier (lowercase). Set for
+    /// every code/manifest/k8s chunk; null for markdown / pdf / image hits.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub code_lang: Option<String>,
 }
 
 #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
@@ -60,6 +118,19 @@ pub struct RetrievalDetail {
     pub vector_rank: Option<u32>,
 }
 
+impl Default for RetrievalDetail {
+    fn default() -> Self {
+        Self {
+            method: SearchMode::Hybrid,
+            fusion_score: 0.0,
+            lexical_score: None,
+            vector_score: None,
+            lexical_rank: None,
+            vector_rank: None,
+        }
+    }
+}
+
 /// Filter for `kb-app::list_docs` (§7.2 DocumentStore::list_documents).
 #[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
 pub struct DocFilter {
@@ -88,3 +159,376 @@ pub struct DocSummary {
     pub parser_version: ParserVersion,
     pub chunker_version: ChunkerVersion,
 }
+
+/// p9-fb-34: caller-supplied output budget knobs for `App::search_with_opts`.
+/// All `None` = no enforcement (existing behavior).
+#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
+pub struct SearchOpts {
+    /// chars/4 approximation of wire JSON token cost. None = no cap.
+    pub max_tokens: Option<usize>,
+    /// Per-hit snippet character cap. None = use config default.
+    pub snippet_chars: Option<usize>,
+    /// Opaque base64 cursor from a previous response. None = first page.
+    pub cursor: Option<String>,
+    /// p9-fb-37: when true, capture pipeline trace (cache bypassed,
+    /// lex / vec pre-fusion lists + timing populated on the response).
+    #[serde(default)]
+    pub trace: bool,
+}
+
+/// p9-fb-37: search retrieval pipeline trace. Populated only when
+/// `SearchOpts.trace = true`; `None` on the wrapping `SearchResponse`
+/// otherwise. `lexical` / `vector` are pre-fusion candidate lists
+/// (each retriever's full output for the fanout query). `rrf_inputs`
+/// is the union (chunk_id) used by RRF, with each side's rank
+/// captured. `timing` is wall-clock per stage.
+#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
+pub struct SearchTrace {
+    pub lexical: Vec<TraceCandidate>,
+    pub vector: Vec<TraceCandidate>,
+    pub rrf_inputs: Vec<TraceFusionInput>,
+    pub timing: TraceTiming,
+}
+
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+pub struct TraceCandidate {
+    pub chunk_id: ChunkId,
+    pub doc_id: DocumentId,
+    pub doc_path: WorkspacePath,
+    pub rank: u32,
+    pub score: f32,
+}
+
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+pub struct TraceFusionInput {
+    pub chunk_id: ChunkId,
+    pub lexical_rank: Option<u32>,
+    pub vector_rank: Option<u32>,
+    /// Hybrid mode: normalized RRF score in `[0, 1]`.
+    /// Lexical / Vector mode: equals the underlying retriever's score
+    /// (no fusion ran). 0.0 for chunks dropped past `target_k`.
+    pub fusion_score: f32,
+}
+
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub struct TraceTiming {
+    pub lexical_ms: u64,
+    pub vector_ms: u64,
+    pub fusion_ms: u64,
+    pub total_ms: u64,
+}
+
+/// p9-fb-37: on-disk index size breakdown. Mirrored on the
+/// wire `schema.v1.stats.index_bytes` block.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub struct IndexBytes {
+    pub sqlite: u64,
+    pub lancedb: u64,
+}
+
+/// p9-fb-42: per-query result in bulk search. `response` XOR `error` —
+/// exactly one is `Some`. `query` is the input echo (raw JSON value)
+/// so consumers can correlate input to output without index tracking.
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+pub struct BulkSearchItem {
+    pub query: serde_json::Value,
+    pub response: Option<serde_json::Value>,
+    pub error: Option<serde_json::Value>,
+}
+
+/// p9-fb-42: bulk summary counts. Invariant: total == succeeded + failed.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub struct BulkSearchSummary {
+    pub total: u32,
+    pub succeeded: u32,
+    pub failed: u32,
+}
+
+/// p9-fb-42: MCP-only envelope. CLI emits raw ndjson without envelope.
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct BulkSearchResponse {
+    pub schema_version: String,
+    pub results: Vec<BulkSearchItem>,
+    pub summary: BulkSearchSummary,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use time::macros::datetime;
+
+    #[test]
+    fn search_hit_serializes_indexed_at_and_stale() {
+        let hit = SearchHit {
+            rank: 1,
+            chunk_id: ChunkId("c".to_string()),
+            doc_id: DocumentId("d".to_string()),
+            doc_path: WorkspacePath::new("a/b.md".to_string()).unwrap(),
+            heading_path: vec!["H".to_string()],
+            section_label: None,
+            snippet: "s".to_string(),
+            citation: Citation::Line {
+                path: WorkspacePath::new("a/b.md".to_string()).unwrap(),
+                start: 1,
+                end: 1,
+                section: None,
+            },
+            retrieval: RetrievalDetail {
+                method: SearchMode::Lexical,
+                fusion_score: 0.5,
+                lexical_score: Some(0.5),
+                vector_score: None,
+                lexical_rank: Some(1),
+                vector_rank: None,
+            },
+            index_version: IndexVersion("v1".to_string()),
+            embedding_model: None,
+            chunker_version: ChunkerVersion("c1".to_string()),
+            indexed_at: datetime!(2026-05-09 12:00:00 UTC),
+            stale: true,
+            score_kind: ScoreKind::Rrf,
+            repo: None,
+            code_lang: None,
+        };
+        let v = serde_json::to_value(&hit).unwrap();
+        assert_eq!(v["indexed_at"], "2026-05-09T12:00:00Z");
+        assert_eq!(v["stale"], true);
+    }
+
+    #[test]
+    fn search_opts_default_is_all_none() {
+        let opts = SearchOpts::default();
+        assert!(opts.max_tokens.is_none());
+        assert!(opts.snippet_chars.is_none());
+        assert!(opts.cursor.is_none());
+    }
+
+    #[test]
+    fn search_filters_default_includes_new_fb36_fields() {
+        let f = SearchFilters::default();
+        assert!(f.media.is_empty(), "media default empty");
+        assert!(f.ingested_after.is_none(), "ingested_after default None");
+        assert!(f.doc_id.is_none(), "doc_id default None");
+        assert!(f.tags_any.is_empty());
+        assert!(f.lang.is_none());
+        assert!(f.path_glob.is_none());
+        assert!(f.trust_min.is_none());
+    }
+
+    #[test]
+    fn search_filters_serialize_with_serde_default_compat() {
+        let old: SearchFilters = serde_json::from_str(r#"{"tags_any":[],"lang":null,"path_glob":null,"trust_min":null}"#).unwrap();
+        assert!(old.media.is_empty());
+        assert!(old.ingested_after.is_none());
+        assert!(old.doc_id.is_none());
+    }
+
+    #[test]
+    fn search_trace_serde_roundtrip() {
+        let t = SearchTrace {
+            lexical: vec![TraceCandidate {
+                chunk_id: ChunkId("c1".into()),
+                doc_id: DocumentId("d1".into()),
+                doc_path: WorkspacePath::new("a.md".into()).unwrap(),
+                rank: 1,
+                score: 0.42,
+            }],
+            vector: vec![],
+            rrf_inputs: vec![TraceFusionInput {
+                chunk_id: ChunkId("c1".into()),
+                lexical_rank: Some(1),
+                vector_rank: None,
+                fusion_score: 0.0234,
+            }],
+            timing: TraceTiming {
+                lexical_ms: 12,
+                vector_ms: 0,
+                fusion_ms: 1,
+                total_ms: 14,
+            },
+        };
+        let v = serde_json::to_value(&t).unwrap();
+        assert_eq!(v["timing"]["lexical_ms"], 12);
+        assert_eq!(
+            v["lexical"][0]["score"].as_f64().unwrap() as f32,
+            0.42_f32
+        );
+        let back: SearchTrace = serde_json::from_value(v).unwrap();
+        assert_eq!(back, t);
+    }
+
+    #[test]
+    fn index_bytes_default_is_zero() {
+        let b = IndexBytes::default();
+        assert_eq!(b.sqlite, 0);
+        assert_eq!(b.lancedb, 0);
+    }
+
+    #[test]
+    fn search_opts_trace_default_false() {
+        let opts = SearchOpts::default();
+        assert!(!opts.trace);
+    }
+
+    #[test]
+    fn score_kind_serde_roundtrip() {
+        use ScoreKind::*;
+        for (kind, expected) in [(Rrf, "rrf"), (Bm25, "bm25"), (Cosine, "cosine")] {
+            let v = serde_json::to_value(kind).unwrap();
+            assert_eq!(v.as_str(), Some(expected));
+            let back: ScoreKind = serde_json::from_value(v).unwrap();
+            assert_eq!(back, kind);
+        }
+    }
+
+    #[test]
+    fn score_kind_default_is_rrf() {
+        assert_eq!(ScoreKind::default(), ScoreKind::Rrf);
+    }
+
+    #[test]
+    fn search_hit_deserialize_without_score_kind_defaults_to_rrf() {
+        let json = serde_json::json!({
+            "rank": 1,
+            "chunk_id": "c1",
+            "doc_id": "d1",
+            "doc_path": "a.md",
+            "heading_path": [],
+            "section_label": null,
+            "snippet": "x",
+            "citation": { "kind": "line", "path": "a.md", "start": 1, "end": 1, "section": null },
+            "retrieval": {
+                "method": "lexical",
+                "fusion_score": 0.5,
+                "lexical_score": 0.5,
+                "vector_score": null,
+                "lexical_rank": 1,
+                "vector_rank": null
+            },
+            "index_version": "v1",
+            "embedding_model": null,
+            "chunker_version": "c1",
+            "indexed_at": "2026-05-10T12:00:00Z",
+            "stale": false
+        });
+        let hit: SearchHit = serde_json::from_value(json).unwrap();
+        assert_eq!(hit.score_kind, ScoreKind::Rrf);
+    }
+
+    #[test]
+    fn bulk_search_summary_serde_roundtrip() {
+        let s = BulkSearchSummary {
+            total: 5,
+            succeeded: 4,
+            failed: 1,
+        };
+        let v = serde_json::to_value(s).unwrap();
+        assert_eq!(v["total"], 5);
+        assert_eq!(v["succeeded"], 4);
+        assert_eq!(v["failed"], 1);
+        let back: BulkSearchSummary = serde_json::from_value(v).unwrap();
+        assert_eq!(back, s);
+    }
+
+    #[test]
+    fn bulk_search_summary_default_is_zeros() {
+        let s = BulkSearchSummary::default();
+        assert_eq!(s.total, 0);
+        assert_eq!(s.succeeded, 0);
+        assert_eq!(s.failed, 0);
+    }
+
+    #[test]
+    fn bulk_search_item_serde_response_variant() {
+        let item = BulkSearchItem {
+            query: serde_json::json!({"query": "rust"}),
+            response: Some(serde_json::json!({"hits": []})),
+            error: None,
+        };
+        let v = serde_json::to_value(&item).unwrap();
+        assert!(v["response"].is_object());
+        assert!(v["error"].is_null());
+    }
+
+    #[test]
+    fn bulk_search_item_serde_error_variant() {
+        let item = BulkSearchItem {
+            query: serde_json::json!({"query": "rust"}),
+            response: None,
+            error: Some(serde_json::json!({"code": "config_invalid", "message": "bad"})),
+        };
+        let v = serde_json::to_value(&item).unwrap();
+        assert!(v["response"].is_null());
+        assert_eq!(v["error"]["code"], "config_invalid");
+    }
+
+    #[test]
+    fn search_hit_repo_and_code_lang_are_optional_and_omit_when_none() {
+        let hit = SearchHit {
+            rank: 1,
+            chunk_id: ChunkId("c1".into()),
+            doc_id: DocumentId("d1".into()),
+            doc_path: WorkspacePath("a.md".into()),
+            heading_path: vec![],
+            section_label: None,
+            snippet: "".into(),
+            citation: Citation::Line {
+                path: WorkspacePath("a.md".into()),
+                start: 1,
+                end: 2,
+                section: None,
+            },
+            retrieval: RetrievalDetail::default(),
+            index_version: IndexVersion("v1".into()),
+            embedding_model: None,
+            chunker_version: ChunkerVersion("md-heading-v1".into()),
+            indexed_at: time::OffsetDateTime::UNIX_EPOCH,
+            stale: false,
+            score_kind: ScoreKind::Rrf,
+            repo: None,
+            code_lang: None,
+        };
+        let v = serde_json::to_value(&hit).unwrap();
+        assert!(v.get("repo").is_none(), "repo should be omitted when None");
+        assert!(v.get("code_lang").is_none(), "code_lang should be omitted when None");
+    }
+
+    #[test]
+    fn search_hit_repo_and_code_lang_present_when_some() {
+        let hit = SearchHit {
+            rank: 1,
+            chunk_id: ChunkId("c1".into()),
+            doc_id: DocumentId("d1".into()),
+            doc_path: WorkspacePath("a.rs".into()),
+            heading_path: vec![],
+            section_label: None,
+            snippet: "".into(),
+            citation: Citation::Code {
+                path: WorkspacePath("a.rs".into()),
+                line_start: 1,
+                line_end: 2,
+                symbol: None,
+                lang: Some("rust".into()),
+            },
+            retrieval: RetrievalDetail::default(),
+            index_version: IndexVersion("v1".into()),
+            embedding_model: None,
+            chunker_version: ChunkerVersion("code-rust-ast-v1".into()),
+            indexed_at: time::OffsetDateTime::UNIX_EPOCH,
+            stale: false,
+            score_kind: ScoreKind::Rrf,
+            repo: Some("kebab".into()),
+            code_lang: Some("rust".into()),
+        };
+        let v = serde_json::to_value(&hit).unwrap();
+        assert_eq!(v["repo"], "kebab");
+        assert_eq!(v["code_lang"], "rust");
+    }
+
+    #[test]
+    fn search_filters_repo_and_code_lang_default_to_empty_vec() {
+        let f = SearchFilters::default();
+        assert!(f.repo.is_empty());
+        assert!(f.code_lang.is_empty());
+    }
+}

crates/kebab-core/src/traits.rs

@@ -8,7 +8,7 @@ use serde_json::Value;
 use crate::asset::{RawAsset, WorkspacePath};
 use crate::chunk::Chunk;
 use crate::document::{Block, CanonicalDocument};
-use crate::ids::{ChunkId, DocumentId};
+use crate::ids::{AssetId, ChunkId, DocumentId};
 use crate::jobs::{JobFilter, JobId, JobKind, JobRow, JobStatus};
 use crate::media::MediaType;
 use crate::search::{DocFilter, DocSummary, SearchFilters, SearchHit, SearchQuery};
@@ -98,6 +98,11 @@ pub enum FinishReason {
     Stop,
     Length,
     Aborted,
+    /// p9-fb-33: caller-side cancel. The pipeline breaks the LM loop
+    /// when a `Token` send into `AskOpts.stream_sink` returns
+    /// `SendError` (receiver dropped). The persisted answer is
+    /// flagged with `RefusalReason::LlmStreamAborted`.
+    Cancelled,
     Error(String),
 }
 
@@ -156,14 +161,51 @@ pub trait DocumentStore {
     fn get_document(&self, id: &DocumentId) -> anyhow::Result<Option<CanonicalDocument>>;
     fn get_chunk(&self, id: &ChunkId) -> anyhow::Result<Option<Chunk>>;
     fn list_documents(&self, filter: &DocFilter) -> anyhow::Result<Vec<DocSummary>>;
+    /// Look up an asset row by its `asset_id` (PRIMARY KEY = blake3
+    /// content hash). Twin-file safe: asset_id is PK so there is
+    /// exactly one row per unique content hash, regardless of how many
+    /// `documents` rows share it. Use this instead of
+    /// `get_asset_by_workspace_path` when you already have a
+    /// `CanonicalDocument` (which carries `source_asset_id`).
+    fn get_asset(&self, id: &AssetId) -> anyhow::Result<Option<RawAsset>>;
+
     /// p9-fb-23: look up an asset row by its workspace path. Used by
     /// the incremental-ingest skip path to compare the freshly
     /// computed blake3 checksum against what's already in SQLite. The
     /// schema enforces a unique workspace_path per asset.
+    ///
+    /// NOTE: for twin files (identical content at different paths),
+    /// `assets.workspace_path` is "last-registered path" — it
+    /// flip-flops on every ingest. Prefer `get_asset` (by asset_id)
+    /// when you have a `CanonicalDocument.source_asset_id`.
     fn get_asset_by_workspace_path(
         &self,
         path: &WorkspacePath,
     ) -> anyhow::Result<Option<RawAsset>>;
+
+    /// Look up a document row by its workspace path. Used by the
+    /// document-centric skip path in `try_skip_unchanged` to avoid the
+    /// twin-file flip-flop that the asset-side lookup suffers from
+    /// (multiple files with identical content share one `assets` row
+    /// whose `workspace_path` is overwritten on every UPSERT, so
+    /// `get_asset_by_workspace_path` returns the wrong twin's path).
+    ///
+    /// `documents.workspace_path` is UNIQUE (V001), so each twin has
+    /// its own stable document row regardless of the asset de-dup.
+    fn get_document_by_workspace_path(
+        &self,
+        path: &WorkspacePath,
+    ) -> anyhow::Result<Option<CanonicalDocument>>;
+
+    /// Return every `workspace_path` stored in the `documents` table.
+    ///
+    /// Used by the post-walker sweep in `kebab-app::ingest` to detect
+    /// documents whose source file has been deleted from the filesystem.
+    /// The set difference `(stored - scanned)` yields orphan candidates;
+    /// each candidate is then existence-checked on disk so that
+    /// out-of-scope files (config narrowing) are NOT purged — only truly
+    /// absent files trigger the purge.
+    fn all_workspace_paths(&self) -> anyhow::Result<Vec<WorkspacePath>>;
 }
 
 pub trait VectorStore {

crates/kebab-embed-local/Cargo.toml

@@ -5,14 +5,14 @@ edition       = { workspace = true }
 rust-version  = { workspace = true }
 license       = { workspace = true }
 repository    = { workspace = true }
-description   = "Local fastembed-rs adapter implementing kb_core::Embedder (multilingual-e5-small default)"
+description   = "Local fastembed-rs adapter implementing kb_core::Embedder (multilingual-e5-large default, e5-small backwards-compat)"
 
 [dependencies]
 kebab-config = { path = "../kebab-config" }
 kebab-embed = { path = "../kebab-embed" }
 # Default features bring `ort-download-binaries` (bundled ONNX runtime)
 # and `hf-hub-native-tls` (first-run model download). No extra features
-# needed for the multilingual-e5-small path.
+# needed for the multilingual-e5-{small,large} paths.
 fastembed = { workspace = true }
 tracing   = { workspace = true }
 anyhow    = { workspace = true }

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

@@ -1,8 +1,9 @@
 //! `kb-embed-local` — `FastembedEmbedder`, a local ONNX-backed
 //! [`Embedder`](kebab_embed::Embedder) implementation.
 //!
-//! Wraps [`fastembed::TextEmbedding`] for the default `multilingual-e5-small`
-//! (384-dim) model. Honors `config.models.embedding.batch_size` and applies
+//! Wraps [`fastembed::TextEmbedding`]. Default is `multilingual-e5-large`
+//! (1024-dim, p9-fb-39b); `multilingual-e5-small` (384-dim) is also supported
+//! for backwards-compat. Honors `config.models.embedding.batch_size` and applies
 //! the e5 prefix convention (§11.3 of the design report):
 //!
 //! * `EmbeddingKind::Document` → `"passage: "` prefix
@@ -69,9 +70,9 @@ impl FastembedEmbedder {
             .with_context(|| format!("create fastembed cache dir {}", cache_dir.display()))?;
 
         // 2. Resolve the fastembed enum variant from
-        //    `config.models.embedding.model`. Currently only the default
-        //    `multilingual-e5-small` is wired; other model names error
-        //    out with a clear message rather than silently misconfiguring.
+        //    `config.models.embedding.model`. Currently `multilingual-e5-large`
+        //    (default) and `multilingual-e5-small` are wired; other model names
+        //    error out with a clear message rather than silently misconfiguring.
         let model_name = resolve_model(&config.models.embedding.model)?;
 
         // 3. Verify dim match BEFORE loading the model — if the config
@@ -100,7 +101,7 @@ impl FastembedEmbedder {
             target: "kebab-embed-local",
             model = %config.models.embedding.model,
             cache_dir = %cache_dir.display(),
-            "loading embedding model (first run will download ~470MB)"
+            "loading embedding model (first run downloads model weights — ~470MB for e5-small, ~1.3GB for e5-large)"
         );
         let inner = TextEmbedding::try_new(opts)
             .context("fastembed: TextEmbedding::try_new")?;
@@ -193,17 +194,18 @@ fn prefix_input(input: &EmbeddingInput<'_>) -> String {
 }
 
 /// Resolve a `config.models.embedding.model` string to a fastembed
-/// `EmbeddingModel` enum variant. Only `multilingual-e5-small` is wired
-/// for p3-2; additional model names should be added (and their dims
-/// pinned in tests) as needed.
+/// `EmbeddingModel` enum variant. Currently supports `multilingual-e5-small`
+/// (384-dim) and `multilingual-e5-large` (1024-dim); additional model names
+/// should be added (and their dims pinned in tests) as needed.
 fn resolve_model(name: &str) -> Result<EmbeddingModel> {
     match name {
         "multilingual-e5-small" => Ok(EmbeddingModel::MultilingualE5Small),
+        "multilingual-e5-large" => Ok(EmbeddingModel::MultilingualE5Large),
         other => anyhow::bail!(
             "kb-embed-local: unsupported embedding model {other:?}; \
-             this adapter currently only ships `multilingual-e5-small`. \
-             Add a new arm to `resolve_model` (and a fastembed feature \
-             flag if needed) to support more."
+             this adapter currently ships `multilingual-e5-small` and \
+             `multilingual-e5-large`. Add a new arm to `resolve_model` \
+             (and a fastembed feature flag if needed) to support more."
         ),
     }
 }
@@ -294,6 +296,12 @@ mod tests {
         resolve_model("multilingual-e5-small").expect("default model resolves");
     }
 
+    #[test]
+    fn resolve_model_supports_e5_large() {
+        let m = resolve_model("multilingual-e5-large").expect("e5-large should resolve");
+        let _ = m;
+    }
+
     #[test]
     fn resolve_unknown_model_errors() {
         let err = resolve_model("not-a-real-model").expect_err("unknown model errors");
@@ -301,6 +309,21 @@ mod tests {
         assert!(msg.contains("unsupported embedding model"), "msg={msg}");
     }
 
+    // ── check_dim ────────────────────────────────────────────────────
+
+    #[test]
+    fn check_dim_passes_for_1024() {
+        check_dim(1024, 1024).expect("matching dims must pass");
+    }
+
+    #[test]
+    fn check_dim_rejects_384_vs_1024() {
+        let err = check_dim(384, 1024).expect_err("dim mismatch must error");
+        let msg = format!("{err}");
+        assert!(msg.contains("384") && msg.contains("1024"),
+            "error must mention both dims, got: {msg}");
+    }
+
     // expand_path tests live in `kb-config::paths`. The adapter imports
     // it and trusts the upstream coverage rather than duplicating it.
 }

crates/kebab-embed-local/tests/embed_model.rs

@@ -3,10 +3,11 @@
 //!
 //! ## Why every test in this file is `#[ignore]`
 //!
-//! The first call to `FastembedEmbedder::new` downloads ~470 MB of
-//! weights from Hugging Face into `data_dir/models/fastembed/`. Doing
-//! that on every `cargo test` invocation is wasteful, so the bare
-//! invocation skips this file entirely.
+//! The first call to `FastembedEmbedder::new` downloads ~1.3 GB of
+//! weights (multilingual-e5-large per p9-fb-39b default) from Hugging
+//! Face into `data_dir/models/fastembed/`. Doing that on every
+//! `cargo test` invocation is wasteful, so the bare invocation skips
+//! this file entirely.
 //!
 //! Run the full suite with:
 //! ```text
@@ -58,19 +59,20 @@ fn shared_embedder() -> &'static FastembedEmbedder {
 // ─── construction ─────────────────────────────────────────────────────
 
 #[test]
-#[ignore = "downloads ~470MB ONNX model on first run; CI-only"]
-fn default_config_constructs_with_dims_384() {
+#[ignore = "downloads ~1.3GB ONNX model on first run; CI-only"]
+fn default_config_constructs_with_dims_1024() {
+    // p9-fb-39b: default flipped to multilingual-e5-large (1024 dim).
     let emb = shared_embedder();
-    assert_eq!(emb.dimensions(), 384);
-    assert_eq!(emb.model_id().0, "multilingual-e5-small");
+    assert_eq!(emb.dimensions(), 1024);
+    assert_eq!(emb.model_id().0, "multilingual-e5-large");
     assert_eq!(emb.model_version().0, "v1");
 }
 
 #[test]
-#[ignore = "downloads ~470MB ONNX model on first run; CI-only"]
+#[ignore = "downloads ~1.3GB ONNX model on first run; CI-only"]
 fn mismatched_dims_in_config_errors_at_construction() {
     let (mut cfg, _tmp) = test_config();
-    cfg.models.embedding.dimensions = 512; // model is 384
+    cfg.models.embedding.dimensions = 512; // model is 1024 (e5-large default)
     // `FastembedEmbedder` deliberately does not implement `Debug`
     // (its inner ONNX session has no useful debug shape), so we
     // can't use `expect_err`; match the Result manually.
@@ -80,7 +82,7 @@ fn mismatched_dims_in_config_errors_at_construction() {
     };
     let msg = format!("{err}");
     assert!(msg.contains("dimension mismatch"), "msg={msg}");
-    assert!(msg.contains("384"), "msg={msg}");
+    assert!(msg.contains("1024"), "msg={msg}");
     assert!(msg.contains("512"), "msg={msg}");
 }
 
@@ -104,8 +106,8 @@ fn document_and_query_yield_different_vectors() {
         ])
         .expect("embed two inputs");
     assert_eq!(out.len(), 2);
-    assert_eq!(out[0].len(), 384);
-    assert_eq!(out[1].len(), 384);
+    assert_eq!(out[0].len(), 1024);
+    assert_eq!(out[1].len(), 1024);
 
     // Both vectors are L2-normalized → cosine similarity == dot product.
     let cos: f32 = out[0]
@@ -142,11 +144,11 @@ fn output_vectors_are_l2_normalized() {
     ];
     let out = emb.embed(&inputs).expect("embed");
     // Per `kebab_embed::assert_unit_norm` docs: `5e-4` is the safe bound at
-    // 384 dims (f32::EPSILON × √384 ≈ 2.3e-6, but ONNX kernels add
+    // 1024 dims (f32::EPSILON × √1024 ≈ 2.3e-6, but ONNX kernels add
     // their own per-component noise; 1e-3 is very generous and matches
     // the spec's `± 1e-3`).
     kebab_embed::assert_unit_norm(&out, 1e-3);
-    kebab_embed::assert_vector_shape(&out, 384);
+    kebab_embed::assert_vector_shape(&out, 1024);
 }
 
 // ─── determinism ──────────────────────────────────────────────────────
@@ -254,7 +256,7 @@ fn snapshot_aggregate_hash_is_stable() {
     // Round every component to 4 decimal places, hash deterministically.
     let mut hasher = DefaultHasher::new();
     for (i, v) in out.iter().enumerate() {
-        assert_eq!(v.len(), 384, "row {i} dim mismatch");
+        assert_eq!(v.len(), 1024, "row {i} dim mismatch");
         for x in v {
             let rounded: i32 = (*x * 1.0e4).round() as i32;
             rounded.hash(&mut hasher);

crates/kebab-eval/src/compare.rs

@@ -184,6 +184,18 @@ pub fn render_report_md(report: &CompareReport) -> String {
             ),
         );
     }
+    for k in crate::metrics::TOP_K_VARIANTS {
+        let _ = writeln!(
+            out,
+            "| precision@{k}_chunk | {} | {} | {} |",
+            fmt(a.precision_at_k_chunk.get(k).copied().unwrap_or(f32::NAN)),
+            fmt(b.precision_at_k_chunk.get(k).copied().unwrap_or(f32::NAN)),
+            fmt_delta(
+                a.precision_at_k_chunk.get(k).copied().unwrap_or(f32::NAN),
+                b.precision_at_k_chunk.get(k).copied().unwrap_or(f32::NAN),
+            ),
+        );
+    }
     let _ = writeln!(
         out,
         "| citation_coverage | {} | {} | {} |",
@@ -419,6 +431,7 @@ fn build_deltas(
     }
     let mut hit = serde_json::Map::new();
     let mut recall = serde_json::Map::new();
+    let mut precision = serde_json::Map::new();
     for k in crate::metrics::TOP_K_VARIANTS {
         hit.insert(
             k.to_string(),
@@ -434,11 +447,19 @@ fn build_deltas(
                 b.recall_at_k_doc.get(k).copied().unwrap_or(f32::NAN),
             ),
         );
+        precision.insert(
+            k.to_string(),
+            d(
+                a.precision_at_k_chunk.get(k).copied().unwrap_or(f32::NAN),
+                b.precision_at_k_chunk.get(k).copied().unwrap_or(f32::NAN),
+            ),
+        );
     }
     serde_json::json!({
         "hit_at_k": hit,
         "mrr": d(a.mrr, b.mrr),
         "recall_at_k_doc": recall,
+        "precision_at_k_chunk": precision,
         "citation_coverage": d(a.citation_coverage, b.citation_coverage),
         "groundedness": d(a.groundedness, b.groundedness),
         "empty_result_rate": d(a.empty_result_rate, b.empty_result_rate),
@@ -484,6 +505,7 @@ mod tests {
             hit_at_k: Default::default(),
             mrr: 0.5,
             recall_at_k_doc: Default::default(),
+            precision_at_k_chunk: Default::default(),
             citation_coverage: f32::NAN,
             groundedness: 0.0,
             empty_result_rate: 0.0,

crates/kebab-eval/src/metrics.rs

@@ -58,6 +58,14 @@ pub struct AggregateMetrics {
     pub hit_at_k: BTreeMap<u32, f32>,
     pub mrr: f32,
     pub recall_at_k_doc: BTreeMap<u32, f32>,
+    /// p9-fb-39: chunk-level precision at k. Binary relevance via
+    /// `expected_chunk_ids` (a hit is "relevant" if its chunk_id is
+    /// in the golden's `expected_chunk_ids`). Denominator is k (fixed)
+    /// — `hits.len() < k` still divides by k, treating shortfall as
+    /// precision loss (mirrors `hit_at_k`). Queries with empty
+    /// `expected_chunk_ids` are skipped (mirrors `hit_at_k_chunk`).
+    #[serde(default)]
+    pub precision_at_k_chunk: BTreeMap<u32, f32>,
     #[serde(
         serialize_with = "serialize_f32_nan_as_null",
         deserialize_with = "deserialize_f32_or_nan"
@@ -187,6 +195,8 @@ pub(crate) fn aggregate_from_rows(
         TOP_K_VARIANTS.iter().map(|k| (*k, (0_u32, 0_u32))).collect();
     let mut recall_at_k_doc: BTreeMap<u32, (f64, u32)> =
         TOP_K_VARIANTS.iter().map(|k| (*k, (0.0_f64, 0_u32))).collect();
+    let mut precision_at_k_chunk: BTreeMap<u32, (f64, u32)> =
+        TOP_K_VARIANTS.iter().map(|k| (*k, (0.0_f64, 0_u32))).collect();
 
     let mut mrr_sum: f64 = 0.0;
     let mut mrr_denom: u32 = 0;
@@ -243,6 +253,18 @@ pub(crate) fn aggregate_from_rows(
             {
                 mrr_sum += 1.0 / f64::from(rank);
             }
+            // p9-fb-39: precision@k_chunk — count of top-k hits whose
+            // chunk_id is in `expected`, divided by k (fixed denominator).
+            for k in TOP_K_VARIANTS {
+                let hits_in_topk_relevant = qr
+                    .hits_top_k
+                    .iter()
+                    .filter(|h| h.rank <= *k && expected.contains(&h.chunk_id))
+                    .count();
+                let entry = precision_at_k_chunk.get_mut(k).expect("init");
+                entry.0 += hits_in_topk_relevant as f64 / f64::from(*k);
+                entry.1 += 1;
+            }
         }
 
         // recall@k_doc (doc-level, requires non-empty expected_doc_ids
@@ -316,7 +338,8 @@ pub(crate) fn aggregate_from_rows(
                         | Citation::Page { path, .. }
                         | Citation::Region { path, .. }
                         | Citation::Caption { path, .. }
-                        | Citation::Time { path, .. } => !path.0.is_empty(),
+                        | Citation::Time { path, .. }
+                        | Citation::Code { path, .. } => !path.0.is_empty(),
                     });
                 if covered {
                     citation_num += 1;
@@ -333,6 +356,7 @@ pub(crate) fn aggregate_from_rows(
             mrr_sum / f64::from(mrr_denom)
         }),
         recall_at_k_doc: round_recall_map(&recall_at_k_doc),
+        precision_at_k_chunk: round_recall_map(&precision_at_k_chunk),
         citation_coverage: ratio_or_nan(citation_num, citation_denom),
         groundedness: ratio_or_zero(groundedness_num, groundedness_denom),
         empty_result_rate: ratio_or_zero(empty_result_count, total_queries),
@@ -444,6 +468,13 @@ mod tests {
             index_version: IndexVersion(format!("idx@{rank}")),
             embedding_model: None,
             chunker_version: ChunkerVersion("test@1".into()),
+            // fb-32: synthetic eval fixtures don't exercise staleness;
+            // pin UNIX_EPOCH + stale=false so hits stay deterministic.
+            indexed_at: OffsetDateTime::UNIX_EPOCH,
+            stale: false,
+            score_kind: kebab_core::ScoreKind::Rrf,
+            repo: None,
+            code_lang: None,
         }
     }
 
@@ -479,6 +510,9 @@ mod tests {
                     end: 1,
                     section: None,
                 },
+                // fb-32: synthetic eval citations don't exercise staleness.
+                indexed_at: OffsetDateTime::UNIX_EPOCH,
+                stale: false,
             }).collect(),
             grounded,
             refusal_reason: None,
@@ -666,4 +700,114 @@ mod tests {
         assert_eq!(agg.failed_queries, 1);
         assert_eq!(agg.total_queries, 1);
     }
+
+    #[test]
+    fn precision_at_k_chunk_field_default_empty_on_old_json() {
+        // Old eval_runs.metrics_json predates fb-39 — no precision_at_k_chunk field.
+        // serde(default) yields empty BTreeMap.
+        let old = serde_json::json!({
+            "hit_at_k": {"1": 0.5, "3": 0.5, "5": 0.5, "10": 0.5},
+            "mrr": 0.5,
+            "recall_at_k_doc": {"1": 0.0, "3": 0.0, "5": 0.0, "10": 0.0},
+            "citation_coverage": null,
+            "groundedness": 0.0,
+            "empty_result_rate": 0.0,
+            "refusal_correctness": null,
+            "total_queries": 1,
+            "failed_queries": 0
+        });
+        let parsed: AggregateMetrics =
+            serde_json::from_value(old).expect("backwards-compat deserialize");
+        assert!(parsed.precision_at_k_chunk.is_empty());
+    }
+
+    #[test]
+    fn precision_at_k_chunk_exact_match() {
+        // expected = [c1, c2, c3]. Top-5 hits: [c1@1, c2@2, c3@3, x@4, y@5].
+        // P@5 = 3/5 = 0.6. P@10 = 3/10 = 0.3.
+        let queries = vec![gq("q1", &["c1", "c2", "c3"], &["d1"])];
+        let rows = vec![record(
+            "q1",
+            vec![
+                hit(1, "c1", "d1"),
+                hit(2, "c2", "d1"),
+                hit(3, "c3", "d1"),
+                hit(4, "x", "d1"),
+                hit(5, "y", "d1"),
+            ],
+            None,
+            None,
+        )];
+        let agg = aggregate_from_rows(&queries, &rows).unwrap();
+        assert_eq!(agg.precision_at_k_chunk[&5], 0.6);
+        assert_eq!(agg.precision_at_k_chunk[&10], 0.3);
+    }
+
+    #[test]
+    fn precision_at_k_chunk_partial_topk_divides_by_k() {
+        // expected = [c1, c2]. Hits: only [c1@1, c2@2, x@3] (3 results).
+        // P@5 = 2/5 = 0.4 (denominator is k, not hits.len()).
+        let queries = vec![gq("q1", &["c1", "c2"], &["d1"])];
+        let rows = vec![record(
+            "q1",
+            vec![hit(1, "c1", "d1"), hit(2, "c2", "d1"), hit(3, "x", "d1")],
+            None,
+            None,
+        )];
+        let agg = aggregate_from_rows(&queries, &rows).unwrap();
+        assert_eq!(agg.precision_at_k_chunk[&5], 0.4);
+        assert_eq!(agg.precision_at_k_chunk[&10], 0.2);
+    }
+
+    #[test]
+    fn precision_at_k_chunk_zero_relevant_in_topk() {
+        // expected = [c1]. Hits: [x@1, y@2, z@3] (none relevant).
+        // P@5 = 0/5 = 0.0.
+        let queries = vec![gq("q1", &["c1"], &["d1"])];
+        let rows = vec![record(
+            "q1",
+            vec![hit(1, "x", "d1"), hit(2, "y", "d1"), hit(3, "z", "d1")],
+            None,
+            None,
+        )];
+        let agg = aggregate_from_rows(&queries, &rows).unwrap();
+        assert_eq!(agg.precision_at_k_chunk[&5], 0.0);
+    }
+
+    #[test]
+    fn precision_at_k_chunk_empty_expected_skipped() {
+        // expected_chunk_ids = []. Skipped → final BTreeMap entry value = 0.0
+        // (zero-denom path in round_recall_map). Mirrors recall_at_k_doc behavior.
+        let queries = vec![gq("q1", &[], &["d1"])];
+        let rows = vec![record("q1", vec![hit(1, "c1", "d1")], None, None)];
+        let agg = aggregate_from_rows(&queries, &rows).unwrap();
+        assert_eq!(agg.precision_at_k_chunk[&5], 0.0);
+    }
+
+    #[test]
+    fn precision_at_k_chunk_two_queries_averaged() {
+        // q1: expected=[c1], hits=[c1@1, x@2, y@3]   → P@5 = 1/5 = 0.2
+        // q2: expected=[c1, c2], hits=[c1@1, c2@2]  → P@5 = 2/5 = 0.4
+        // Avg P@5 = 0.3.
+        let queries = vec![
+            gq("q1", &["c1"], &["d1"]),
+            gq("q2", &["c1", "c2"], &["d2"]),
+        ];
+        let rows = vec![
+            record(
+                "q1",
+                vec![hit(1, "c1", "d1"), hit(2, "x", "d1"), hit(3, "y", "d1")],
+                None,
+                None,
+            ),
+            record(
+                "q2",
+                vec![hit(1, "c1", "d2"), hit(2, "c2", "d2")],
+                None,
+                None,
+            ),
+        ];
+        let agg = aggregate_from_rows(&queries, &rows).unwrap();
+        assert_eq!(agg.precision_at_k_chunk[&5], 0.3);
+    }
 }

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

@@ -11,6 +11,12 @@
       "5": 0.666700005531311
     },
     "mrr": 0.41670000553131104,
+    "precision_at_k_chunk": {
+      "1": 0.33329999446868896,
+      "10": 0.06669999659061432,
+      "3": 0.11110000312328339,
+      "5": 0.13330000638961792
+    },
     "recall_at_k_doc": {
       "1": 0.33329999446868896,
       "10": 0.666700005531311,
@@ -32,6 +38,12 @@
       "5": 1.0
     },
     "mrr": 0.833299994468689,
+    "precision_at_k_chunk": {
+      "1": 0.666700005531311,
+      "10": 0.10000000149011612,
+      "3": 0.33329999446868896,
+      "5": 0.20000000298023224
+    },
     "recall_at_k_doc": {
       "1": 0.666700005531311,
       "10": 1.0,
@@ -53,6 +65,12 @@
       "5": 0.33329999446868896
     },
     "mrr": 0.41659998893737793,
+    "precision_at_k_chunk": {
+      "1": 0.33340001106262207,
+      "10": 0.0333000048995018,
+      "3": 0.22219999134540558,
+      "5": 0.06669999659061432
+    },
     "recall_at_k_doc": {
       "1": 0.33340001106262207,
       "10": 0.33329999446868896,

crates/kebab-eval/tests/metrics_and_compare.rs

@@ -82,6 +82,13 @@ fn hit(rank: u32, chunk_id: &str, doc_id: &str) -> SearchHit {
         index_version: IndexVersion("idx@1".into()),
         embedding_model: None,
         chunker_version: ChunkerVersion("test@1".into()),
+        // fb-32: synthetic eval fixtures don't exercise staleness;
+        // pin UNIX_EPOCH + stale=false so hits stay deterministic.
+        indexed_at: OffsetDateTime::UNIX_EPOCH,
+        stale: false,
+        score_kind: kebab_core::ScoreKind::Rrf,
+        repo: None,
+        code_lang: None,
     }
 }
 
@@ -198,6 +205,7 @@ fn store_aggregate_rejects_missing_run() {
         hit_at_k: Default::default(),
         mrr: 0.0,
         recall_at_k_doc: Default::default(),
+        precision_at_k_chunk: Default::default(),
         citation_coverage: f32::NAN,
         groundedness: 0.0,
         empty_result_rate: 0.0,

crates/kebab-eval/tests/runner.rs

@@ -213,7 +213,7 @@ fn runner_records_config_snapshot_with_versions() {
     assert!(snap.pointer("/llm/model_id").is_some());
     assert_eq!(
         snap.pointer("/prompt_template_version"),
-        Some(&serde_json::Value::String("rag-v1".to_string())),
+        Some(&serde_json::Value::String("rag-v2".to_string())),
     );
     assert!(snap.pointer("/score_gate").is_some());
     assert!(snap.pointer("/rrf_k").is_some());
@@ -336,21 +336,29 @@ fn runner_lexical_is_deterministic_per_query_payload() {
         "- id: q1\n  query: ownership\n- id: q2\n  query: heading\n",
     );
 
-    let run_a = run_with_golden(&yaml, || {
+    let mut run_a = run_with_golden(&yaml, || {
         run_eval_with_config(&env.config, &lexical_opts()).unwrap()
     });
-    let run_b = run_with_golden(&yaml, || {
+    let mut run_b = run_with_golden(&yaml, || {
         run_eval_with_config(&env.config, &lexical_opts()).unwrap()
     });
 
     // Run-level fields (`run_id`, `created_at`) intentionally diverge;
     // the per-query payload (which is what the snapshot fixture pins)
-    // must be byte-identical.
+    // must be byte-identical EXCEPT for `elapsed_ms`. Timing-sensitive
+    // fields aren't determinism signals — they're µs-scale wall-clock
+    // jitter and would otherwise make this assertion a flaky one (a 0
+    // vs 1 ms divergence was observed under contended-CI load). Normalize
+    // before comparing; see test #7 for the same exclusion done via a
+    // projection.
+    for qr in run_a.per_query.iter_mut().chain(run_b.per_query.iter_mut()) {
+        qr.elapsed_ms = 0;
+    }
     let a_json = serde_json::to_string(&run_a.per_query).unwrap();
     let b_json = serde_json::to_string(&run_b.per_query).unwrap();
     assert_eq!(
         a_json, b_json,
-        "lexical-only per_query payload must be byte-identical across runs"
+        "lexical-only per_query payload must be byte-identical across runs (timing normalized)"
     );
 }
 

crates/kebab-mcp/Cargo.toml

@@ -0,0 +1,29 @@
+[package]
+name        = "kebab-mcp"
+edition     = { workspace = true }
+rust-version = { workspace = true }
+license     = { workspace = true }
+repository  = { workspace = true }
+version     = { workspace = true }
+
+[dependencies]
+rmcp        = { workspace = true }
+# rt-multi-thread + io-util + io-std extend the workspace tokio entry
+# (which only declares rt + macros) for the blocking stdio MCP transport.
+tokio       = { workspace = true, features = ["rt-multi-thread", "macros", "io-util", "io-std"] }
+serde       = { workspace = true }
+serde_json  = { workspace = true }
+anyhow      = { workspace = true }
+tracing     = { workspace = true }
+# schemars 1.x matches rmcp 1.6's ^1.0 requirement (verified via crates.io
+# /dependencies endpoint — rmcp declares optional schemars = "^1.0").
+schemars    = "1"
+
+time         = { workspace = true }
+
+kebab-app    = { path = "../kebab-app" }
+kebab-config = { path = "../kebab-config" }
+kebab-core   = { path = "../kebab-core" }
+
+[dev-dependencies]
+tempfile = { workspace = true }

crates/kebab-mcp/src/error.rs

@@ -0,0 +1,22 @@
+//! Map `anyhow::Error` returned by kebab-app facades to MCP
+//! `CallToolResult` with `isError: true` + error.v1 JSON content.
+
+use rmcp::model::{CallToolResult, Content};
+
+use kebab_app::classify;
+
+/// Convert an `anyhow::Error` to a `CallToolResult` with `isError: true`
+/// and the serialised `error.v1` envelope as the text content.
+pub fn to_tool_error(err: &anyhow::Error) -> CallToolResult {
+    let v1 = classify(err, false);
+    let body = serde_json::to_string(&v1).unwrap_or_else(|_| {
+        r#"{"schema_version":"error.v1","code":"generic","message":"serialize failed"}"#
+            .to_string()
+    });
+    CallToolResult::error(vec![Content::text(body)])
+}
+
+/// Wrap a successful wire-schema JSON string as a `CallToolResult`.
+pub fn to_tool_success(json: String) -> CallToolResult {
+    CallToolResult::success(vec![Content::text(json)])
+}

crates/kebab-mcp/src/lib.rs

@@ -0,0 +1,213 @@
+//! MCP (Model Context Protocol) server over stdio. Exposes 8 tools
+//! (`search` / `ask` / `schema` / `doctor` / `ingest_file` / `ingest_stdin`
+//! / `fetch` / `bulk_search`) backed by `kebab-app` facade methods. Used by
+//! `kebab-cli`'s `Cmd::Mcp` arm.
+//!
+//! See spec `docs/superpowers/specs/2026-05-07-p9-fb-30-mcp-server-design.md`.
+
+use std::path::PathBuf;
+
+use anyhow::Result;
+
+use rmcp::ServerHandler;
+use rmcp::handler::server::common::{schema_for_empty_input, schema_for_type};
+use rmcp::model::{
+    CallToolRequestParams, CallToolResult, Implementation, ListToolsResult, ServerCapabilities,
+    ServerInfo, Tool,
+};
+use rmcp::service::{RequestContext, ServiceExt};
+use rmcp::transport::stdio;
+use rmcp::{ErrorData, RoleServer};
+
+use kebab_config::Config;
+
+pub mod error;
+pub mod state;
+pub mod tools;
+pub use state::KebabAppState;
+
+/// Build the canonical list of tools exposed by the MCP server.
+///
+/// Extracted from [`ServerHandler::list_tools`] so it can be called
+/// directly in tests without constructing a `RequestContext`.
+pub fn build_tools_vec() -> Vec<Tool> {
+    vec![
+        Tool::new(
+            "schema",
+            "Introspection — wire schemas, capabilities, model versions, index stats.",
+            schema_for_empty_input(),
+        ),
+        Tool::new(
+            "doctor",
+            "Health check — verifies config, storage, models, and Ollama connectivity.",
+            schema_for_empty_input(),
+        ),
+        Tool::new(
+            "search",
+            "Full-text / vector / hybrid search over the knowledge base. Returns search_hit.v1 array.",
+            schema_for_type::<tools::search::SearchInput>(),
+        ),
+        Tool::new(
+            "ask",
+            "RAG question answering over the knowledge base. Returns answer.v1 JSON. Pass session_id for multi-turn context.",
+            schema_for_type::<tools::ask::AskInput>(),
+        ),
+        Tool::new(
+            "ingest_file",
+            "Ingest a single file (path) into the knowledge base. Workspace external paths allowed — bytes are copied into _external/.",
+            schema_for_type::<tools::ingest_file::IngestFileInput>(),
+        ),
+        Tool::new(
+            "ingest_stdin",
+            "Ingest markdown content into the knowledge base. v1 markdown only. Frontmatter (title + source_uri) auto-injected.",
+            schema_for_type::<tools::ingest_stdin::IngestStdinInput>(),
+        ),
+        Tool::new(
+            "fetch",
+            "Verbatim fetch — chunk / doc / span modes. Returns fetch_result.v1 with the indexed text (no LLM rewrite).",
+            schema_for_type::<tools::fetch::FetchInput>(),
+        ),
+        Tool::new(
+            "bulk_search",
+            "Bulk multi-query search — N queries per call (cap 100). Each query mirrors the `search` input shape; returns `bulk_search_response.v1` with per-query results + summary. Sequential execution reuses one App instance so cache / embedder cold-start cost amortizes.",
+            schema_for_type::<tools::bulk_search::BulkSearchInput>(),
+        ),
+    ]
+}
+
+#[derive(Clone)]
+pub struct KebabHandler {
+    state: KebabAppState,
+}
+
+impl KebabHandler {
+    pub fn new(state: KebabAppState) -> Self {
+        Self { state }
+    }
+
+    pub fn state(&self) -> &KebabAppState {
+        &self.state
+    }
+
+    /// Spawn a tool handler on the blocking pool. Used by tools that
+    /// transitively touch reqwest::blocking::Client (search, ask) — calling
+    /// from the async dispatch directly panics inside the runtime.
+    async fn spawn_tool<I, F>(
+        &self,
+        args: serde_json::Map<String, serde_json::Value>,
+        handle: F,
+    ) -> Result<CallToolResult, ErrorData>
+    where
+        I: serde::de::DeserializeOwned + Send + 'static,
+        F: FnOnce(KebabAppState, I) -> CallToolResult + Send + 'static,
+    {
+        let input: I = match serde_json::from_value(serde_json::Value::Object(args)) {
+            Ok(i) => i,
+            Err(e) => return Ok(error::to_tool_error(&anyhow::Error::from(e))),
+        };
+        let state = self.state.clone();
+        tokio::task::spawn_blocking(move || handle(state, input))
+            .await
+            .map_err(|e| ErrorData::internal_error(e.to_string(), None))
+    }
+}
+
+impl ServerHandler for KebabHandler {
+    fn get_info(&self) -> ServerInfo {
+        ServerInfo::new(ServerCapabilities::builder().enable_tools().build())
+            .with_server_info(Implementation::new("kebab", env!("CARGO_PKG_VERSION")))
+    }
+
+    async fn list_tools(
+        &self,
+        _request: Option<rmcp::model::PaginatedRequestParams>,
+        _context: RequestContext<RoleServer>,
+    ) -> Result<ListToolsResult, ErrorData> {
+        Ok(ListToolsResult::with_all_items(build_tools_vec()))
+    }
+
+    async fn call_tool(
+        &self,
+        request: CallToolRequestParams,
+        _context: RequestContext<RoleServer>,
+    ) -> Result<CallToolResult, ErrorData> {
+        match request.name.as_ref() {
+            "schema" => {
+                let input = tools::schema::SchemaInput::default();
+                Ok(tools::schema::handle(&self.state, input))
+            }
+            "doctor" => {
+                let input = tools::doctor::DoctorInput::default();
+                Ok(tools::doctor::handle(&self.state, input))
+            }
+            "search" => {
+                let args = request.arguments.unwrap_or_default();
+                self.spawn_tool(args, |state, input| {
+                    tools::search::handle(&state, input)
+                })
+                .await
+            }
+            "ask" => {
+                let args = request.arguments.unwrap_or_default();
+                self.spawn_tool(args, |state, input| {
+                    tools::ask::handle(&state, input)
+                })
+                .await
+            }
+            "ingest_file" => {
+                let args = request.arguments.unwrap_or_default();
+                self.spawn_tool(args, |state, input| {
+                    tools::ingest_file::handle(&state, input)
+                })
+                .await
+            }
+            "ingest_stdin" => {
+                let args = request.arguments.unwrap_or_default();
+                self.spawn_tool(args, |state, input| {
+                    tools::ingest_stdin::handle(&state, input)
+                })
+                .await
+            }
+            "fetch" => {
+                let args = request.arguments.unwrap_or_default();
+                self.spawn_tool(args, |state, input| {
+                    tools::fetch::handle(&state, input)
+                })
+                .await
+            }
+            "bulk_search" => {
+                let args = request.arguments.unwrap_or_default();
+                self.spawn_tool(args, |state, input| {
+                    tools::bulk_search::handle(&state, input)
+                })
+                .await
+            }
+            _other => Err(ErrorData::method_not_found::<
+                rmcp::model::CallToolRequestMethod,
+            >()),
+        }
+    }
+}
+
+/// Run the MCP server on stdio JSON-RPC. Blocks until the client closes
+/// the stream (typically when the agent host exits).
+///
+/// `config_path` is the path passed via `--config <path>`, if any.
+/// It is forwarded to `KebabAppState` so the doctor tool can honour the
+/// same config file the server was started with (falls back to XDG default
+/// when `None`).
+pub fn serve_stdio(cfg: Config, config_path: Option<PathBuf>) -> Result<()> {
+    let runtime = tokio::runtime::Builder::new_multi_thread()
+        .enable_all()
+        .build()?;
+    runtime.block_on(serve_stdio_async(cfg, config_path))
+}
+
+async fn serve_stdio_async(cfg: Config, config_path: Option<PathBuf>) -> Result<()> {
+    tracing::info!("kebab-mcp: starting stdio server");
+    let state = KebabAppState::new(cfg, config_path);
+    let handler = KebabHandler::new(state);
+    let service = handler.serve(stdio()).await?;
+    service.waiting().await?;
+    Ok(())
+}

crates/kebab-mcp/src/state.rs

@@ -0,0 +1,26 @@
+//! Long-lived server state — holds Config so per-request handlers don't
+//! reload from disk. Future: cache opened SqliteStore / Lance handles
+//! here so first tool call pays the cost, subsequent calls hit warm
+//! state.
+
+use std::path::PathBuf;
+use std::sync::Arc;
+
+use kebab_config::Config;
+
+#[derive(Clone)]
+pub struct KebabAppState {
+    pub config: Arc<Config>,
+    /// `--config <path>` from CLI when present, else `None` (XDG default
+    /// fallback applies in `doctor_with_config_path`).
+    pub config_path: Option<PathBuf>,
+}
+
+impl KebabAppState {
+    pub fn new(config: Config, config_path: Option<PathBuf>) -> Self {
+        Self {
+            config: Arc::new(config),
+            config_path,
+        }
+    }
+}

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

@@ -0,0 +1,68 @@
+//! `ask` tool — wraps `kebab_app::ask_with_config` (single-shot) or
+//! `kebab_app::ask_with_session_with_config` when `session_id` is provided.
+//! Input: { query, session_id?, mode? }. Output: answer.v1 JSON.
+//!
+//! `Answer` (kebab-core) does NOT carry a `schema_version` field; we tag
+//! it inline here, matching the pattern from `search.rs`.
+
+use rmcp::model::CallToolResult;
+use schemars::JsonSchema;
+use serde::{Deserialize, Serialize};
+
+use crate::error::{to_tool_error, to_tool_success};
+use crate::state::KebabAppState;
+
+#[derive(Debug, Deserialize, Serialize, JsonSchema)]
+pub struct AskInput {
+    /// The user question.
+    pub query: String,
+    /// Optional session id for multi-turn RAG context.
+    pub session_id: Option<String>,
+    /// Optional retrieval mode override ("lexical" / "vector" / "hybrid"). Default "hybrid".
+    pub mode: Option<String>,
+}
+
+pub fn handle(state: &KebabAppState, input: AskInput) -> CallToolResult {
+    let mode = match input.mode.as_deref() {
+        Some("lexical") => kebab_core::SearchMode::Lexical,
+        Some("vector") => kebab_core::SearchMode::Vector,
+        _ => kebab_core::SearchMode::Hybrid, // default + "hybrid" + unknown
+    };
+    let opts = kebab_app::AskOpts {
+        k: 10,
+        explain: false,
+        mode,
+        temperature: None,
+        seed: None,
+        stream_sink: None,
+        history: Vec::new(),
+        conversation_id: None,
+        turn_index: None,
+    };
+    let cfg_clone = (*state.config).clone();
+    let result = match input.session_id {
+        Some(sid) => {
+            kebab_app::ask_with_session_with_config(cfg_clone, &sid, &input.query, opts)
+        }
+        None => kebab_app::ask_with_config(cfg_clone, &input.query, opts),
+    };
+    match result {
+        Ok(answer) => {
+            // `Answer` does not carry `schema_version`; tag inline (idempotent
+            // via entry().or_insert_with in case a future version adds it).
+            let mut v = match serde_json::to_value(&answer) {
+                Ok(v) => v,
+                Err(e) => return to_tool_error(&anyhow::anyhow!("answer serialize failed: {e}")),
+            };
+            if let serde_json::Value::Object(ref mut map) = v {
+                map.entry("schema_version".to_string())
+                    .or_insert_with(|| serde_json::Value::String("answer.v1".to_string()));
+            }
+            match serde_json::to_string(&v) {
+                Ok(json) => to_tool_success(json),
+                Err(e) => to_tool_error(&anyhow::anyhow!(e)),
+            }
+        }
+        Err(e) => to_tool_error(&e),
+    }
+}

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

@@ -0,0 +1,55 @@
+//! `bulk_search` tool — wraps `kebab_app::bulk_search_with_config`.
+//! Input: `{ queries: [<SearchInput shape>, ...] }`.
+//! Output: `bulk_search_response.v1` envelope (results + summary).
+
+use rmcp::model::CallToolResult;
+use schemars::JsonSchema;
+use serde::{Deserialize, Serialize};
+
+use crate::error::{to_tool_error, to_tool_success};
+use crate::state::KebabAppState;
+
+#[derive(Debug, Deserialize, Serialize, JsonSchema)]
+pub struct BulkSearchInput {
+    /// Per-query inputs. Each item mirrors the single-query `search`
+    /// tool's input shape — `query` is required, all other fields are
+    /// optional and default to single-search defaults. Capped at 100
+    /// items; exceeding returns an `invalid_input` tool error without
+    /// running any query.
+    pub queries: Vec<serde_json::Value>,
+}
+
+pub fn handle(state: &KebabAppState, input: BulkSearchInput) -> CallToolResult {
+    let cfg_clone = (*state.config).clone();
+    match kebab_app::bulk_search_with_config(cfg_clone, input.queries) {
+        Ok((items, summary)) => {
+            let tagged_items: Vec<serde_json::Value> = items
+                .iter()
+                .map(|it| {
+                    let mut v = serde_json::to_value(it).unwrap_or(serde_json::Value::Null);
+                    if let serde_json::Value::Object(ref mut map) = v {
+                        map.insert(
+                            "schema_version".to_string(),
+                            serde_json::Value::String("bulk_search_item.v1".to_string()),
+                        );
+                    }
+                    v
+                })
+                .collect();
+            let envelope = serde_json::json!({
+                "schema_version": "bulk_search_response.v1",
+                "results": tagged_items,
+                "summary": {
+                    "total": summary.total,
+                    "succeeded": summary.succeeded,
+                    "failed": summary.failed,
+                },
+            });
+            match serde_json::to_string(&envelope) {
+                Ok(json) => to_tool_success(json),
+                Err(e) => to_tool_error(&anyhow::anyhow!(e)),
+            }
+        }
+        Err(e) => to_tool_error(&e),
+    }
+}

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

@@ -0,0 +1,28 @@
+//! `doctor` tool — wraps `kebab_app::doctor_with_config_path`.
+//! Input: {} (no args). Output: doctor.v1 JSON.
+//!
+//! `doctor_with_config_path(Option<&Path>)` re-reads config from disk so
+//! the report reflects the live file state. We forward `config_path` from
+//! `KebabAppState` so `--config <path>` users see results for their file;
+//! callers that pass `None` fall back to the XDG default (same as the CLI
+//! bare `kebab doctor`).
+
+use rmcp::model::CallToolResult;
+use schemars::JsonSchema;
+use serde::{Deserialize, Serialize};
+
+use crate::error::{to_tool_error, to_tool_success};
+use crate::state::KebabAppState;
+
+#[derive(Debug, Default, Deserialize, Serialize, JsonSchema)]
+pub struct DoctorInput {}
+
+pub fn handle(state: &KebabAppState, _input: DoctorInput) -> CallToolResult {
+    match kebab_app::doctor_with_config_path(state.config_path.as_deref()) {
+        Ok(report) => match serde_json::to_string(&report) {
+            Ok(json) => to_tool_success(json),
+            Err(e) => to_tool_error(&anyhow::anyhow!(e)),
+        },
+        Err(e) => to_tool_error(&e),
+    }
+}

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

@@ -0,0 +1,99 @@
+//! p9-fb-35 `fetch` tool — wraps `kebab_app::fetch_with_config`.
+//!
+//! Three modes (chunk / doc / span). Output is `fetch_result.v1`.
+//!
+//! Mirrors the CLI surface (`kebab fetch <kind> ...`): same input shape,
+//! same wire envelope. Missing kind-specific fields produce an `error.v1`
+//! with `code = "invalid_input"`.
+
+use rmcp::model::CallToolResult;
+use schemars::JsonSchema;
+use serde::{Deserialize, Serialize};
+
+use crate::error::{to_tool_error, to_tool_success};
+use crate::state::KebabAppState;
+
+#[derive(Debug, Deserialize, Serialize, JsonSchema)]
+pub struct FetchInput {
+    /// "chunk" | "doc" | "span"
+    pub kind: String,
+    /// Required when kind = "chunk".
+    pub chunk_id: Option<String>,
+    /// Required when kind = "doc" or "span".
+    pub doc_id: Option<String>,
+    /// Required when kind = "span" (1-based, inclusive).
+    pub line_start: Option<u32>,
+    pub line_end: Option<u32>,
+    /// chunk only: ±N surrounding chunks.
+    pub context: Option<u32>,
+    /// doc/span only: chars/4 budget.
+    pub max_tokens: Option<usize>,
+}
+
+pub fn handle(state: &KebabAppState, input: FetchInput) -> CallToolResult {
+    let query = match input.kind.as_str() {
+        "chunk" => match input.chunk_id {
+            Some(id) => kebab_core::FetchQuery::Chunk(kebab_core::ChunkId(id)),
+            None => return invalid_input("kind=chunk requires chunk_id"),
+        },
+        "doc" => match input.doc_id {
+            Some(id) => kebab_core::FetchQuery::Doc(kebab_core::DocumentId(id)),
+            None => return invalid_input("kind=doc requires doc_id"),
+        },
+        "span" => match (input.doc_id, input.line_start, input.line_end) {
+            (Some(id), Some(start), Some(end)) => kebab_core::FetchQuery::Span {
+                doc_id: kebab_core::DocumentId(id),
+                line_start: start,
+                line_end: end,
+            },
+            _ => return invalid_input("kind=span requires doc_id, line_start, line_end"),
+        },
+        other => {
+            return invalid_input(&format!(
+                "unknown kind '{other}'; expected chunk|doc|span"
+            ));
+        }
+    };
+
+    let opts = kebab_core::FetchOpts {
+        context: input.context,
+        max_tokens: input.max_tokens,
+    };
+
+    let cfg_clone = (*state.config).clone();
+    match kebab_app::fetch_with_config(cfg_clone, query, opts) {
+        Ok(r) => {
+            // FetchResult does not carry a `schema_version` field, so we
+            // tag the envelope inline (mirrors search.rs's pattern).
+            let mut v = match serde_json::to_value(&r) {
+                Ok(v) => v,
+                Err(e) => {
+                    return to_tool_error(&anyhow::anyhow!("FetchResult serialize: {e}"));
+                }
+            };
+            if let serde_json::Value::Object(ref mut map) = v {
+                map.insert(
+                    "schema_version".to_string(),
+                    serde_json::Value::String("fetch_result.v1".to_string()),
+                );
+            }
+            match serde_json::to_string(&v) {
+                Ok(json) => to_tool_success(json),
+                Err(e) => to_tool_error(&anyhow::anyhow!(e)),
+            }
+        }
+        Err(e) => to_tool_error(&e),
+    }
+}
+
+fn invalid_input(msg: &str) -> CallToolResult {
+    use kebab_app::{ErrorV1, StructuredError};
+    let err = anyhow::Error::new(StructuredError(ErrorV1 {
+        schema_version: "error.v1".to_string(),
+        code: "invalid_input".to_string(),
+        message: msg.to_string(),
+        details: serde_json::Value::Null,
+        hint: None,
+    }));
+    to_tool_error(&err)
+}

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

@@ -0,0 +1,39 @@
+//! `ingest_file` tool — wraps `kebab_app::ingest_file_with_config`.
+//! Input: { path }. Output: ingest_report.v1 JSON.
+
+use std::path::PathBuf;
+
+use rmcp::model::CallToolResult;
+use schemars::JsonSchema;
+use serde::{Deserialize, Serialize};
+
+use crate::error::{to_tool_error, to_tool_success};
+use crate::state::KebabAppState;
+
+#[derive(Debug, Deserialize, Serialize, JsonSchema)]
+pub struct IngestFileInput {
+    /// Absolute or relative path to the file to ingest. Workspace external
+    /// paths are allowed — bytes are copied into `_external/`.
+    pub path: String,
+}
+
+pub fn handle(state: &KebabAppState, input: IngestFileInput) -> CallToolResult {
+    let cfg_clone = (*state.config).clone();
+    let path = PathBuf::from(input.path);
+    match kebab_app::ingest_file_with_config(cfg_clone, &path) {
+        Ok(report) => match serde_json::to_value(&report) {
+            Ok(mut v) => {
+                if let serde_json::Value::Object(ref mut map) = v {
+                    map.entry("schema_version".to_string())
+                        .or_insert_with(|| serde_json::Value::String("ingest_report.v1".to_string()));
+                }
+                match serde_json::to_string(&v) {
+                    Ok(json) => to_tool_success(json),
+                    Err(e) => to_tool_error(&anyhow::anyhow!(e)),
+                }
+            }
+            Err(e) => to_tool_error(&anyhow::anyhow!(e)),
+        },
+        Err(e) => to_tool_error(&e),
+    }
+}

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

@@ -0,0 +1,44 @@
+//! `ingest_stdin` tool — wraps `kebab_app::ingest_stdin_with_config`.
+//! Input: { content, title, source_uri? }. Output: ingest_report.v1 JSON.
+
+use rmcp::model::CallToolResult;
+use schemars::JsonSchema;
+use serde::{Deserialize, Serialize};
+
+use crate::error::{to_tool_error, to_tool_success};
+use crate::state::KebabAppState;
+
+#[derive(Debug, Deserialize, Serialize, JsonSchema)]
+pub struct IngestStdinInput {
+    /// Markdown body content. v1 supports markdown only.
+    pub content: String,
+    /// Title for frontmatter injection.
+    pub title: String,
+    /// Optional source URI (e.g. https URL agent fetched from).
+    pub source_uri: Option<String>,
+}
+
+pub fn handle(state: &KebabAppState, input: IngestStdinInput) -> CallToolResult {
+    let cfg_clone = (*state.config).clone();
+    match kebab_app::ingest_stdin_with_config(
+        cfg_clone,
+        &input.content,
+        &input.title,
+        input.source_uri.as_deref(),
+    ) {
+        Ok(report) => match serde_json::to_value(&report) {
+            Ok(mut v) => {
+                if let serde_json::Value::Object(ref mut map) = v {
+                    map.entry("schema_version".to_string())
+                        .or_insert_with(|| serde_json::Value::String("ingest_report.v1".to_string()));
+                }
+                match serde_json::to_string(&v) {
+                    Ok(json) => to_tool_success(json),
+                    Err(e) => to_tool_error(&anyhow::anyhow!(e)),
+                }
+            }
+            Err(e) => to_tool_error(&anyhow::anyhow!(e)),
+        },
+        Err(e) => to_tool_error(&e),
+    }
+}

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

@@ -0,0 +1,10 @@
+//! Tool implementations — one module per tool.
+
+pub mod schema;
+pub mod doctor;
+pub mod search;
+pub mod ask;
+pub mod ingest_file;
+pub mod ingest_stdin;
+pub mod fetch;
+pub mod bulk_search;