[Epic] v1.5 — Trust & Sources

[mrsibe]

[Epic] v1.5 — Trust & Sources

Theme

One sentence: make every answer auditable at the level of the sentence, and make the sources controllable.

v1.4 (#82) closed the Trusted Research Loop end to end — block-aware chunking, structured citations, a real PDF reader, click-to-source, and an eval harness with a frozen baseline. What it did not change is the grain of the trust: a citation still points at a whole retrieval chunk, and an answer can still sound sourced while one of its sentences is not.

v1.5 is deliberately narrow. It does not add generator features (audio overview, mind map, flashcards, quiz, slides). Those are the features users love; they are not the features users work around. The things users write plugins and forks for — citation precision, source control, folder management, export — are where a small product can beat a large one, and where KnowNote's existing provenance architecture is already an advantage rather than a gap.

The bar

Citation is a link to a location          ← shipped in v1.4
        ↓
Citation is the exact supporting passage  ← this epic
        ↓
A claim without support says so           ← this epic

Children

#	Issue	Priority
#160	Architecture prep: freeze the retrieval / ingestion / citation seams	P0 (step 0)
#155	Exact-passage citation: cite source spans, not chunks	P0
#156	Citation coverage: uncited / invalid / inferred	P0
#94	Source scope, persisted per session	P0/P1
#157	Retrieval explainability (per-answer snapshot)	P1
#95	Ingestion runs: persistent pipeline state, non-destructive re-index	P1
#78	Chunking experiments (freeze the chunk baseline)	P1
#96	Global search + the shared FTS index	P1
#77	Retrieval experiments on the frozen chunk baseline	P1
#98	Batch / folder import	P1
#158	Folder as a live source (watch / re-index / stale)	P1
#80	Knowledge MCP server — stretch, orthogonal	P2

The three workstreams

Trust        #160 → #155 → #156
                        ↑
                       #94 → #157

Source       #95 → #98 → #158

Retrieval    #95 → #78 → #96.buildFTS → #77 → #96.searchUI

The point of #160 is that these three streams share retrieval, ingestion and citation seams. Without it, each stream would grow its own version and KnowledgeService would absorb every one of them.

Build order

Not by issue number — freeze the seam, then stack capability on it.

Order	Work	Why here
0	#160 Architecture prep	Contracts first; no feature work
1	#155 Exact-passage citation	v1.5 core capability
2	#156 Citation coverage	Needs the spans from #155
3	#94 Source scope	First real validation of the RetrievalRequest.filter seam
4	#157 Retrieval explainability	Scope + retrieval trace now exist
5	#95 Ingestion runs	Foundation for everything source-lifecycle
6	#78 Chunking experiments	Fix chunking before tuning retrieval
7	#96 FTS backend	One index shared by search and BM25
8	#77 BM25 / hybrid / RRF / reranker	Measured on the frozen chunk baseline
9	#96 Search UI	Backend already exists
10	#98 Batch / folder import	On the unified ingestion pipeline
11	#158 Watched folder	Filesystem events only enqueue
12	#80 MCP	Adapter over the now-stable query layer

The one ordering rule worth stating separately: #78 before #77. Chunking is the input distribution retrieval is measured on; tuning retrieval and then changing chunking voids the experiment.

Already shipped in v1.4, not re-opened here

• Source reader ([Feat] Source Reader architecture — PDF first (replace the chunk-concatenation <pre> viewer) #71) and citation click → open at page/block ([Feat] Citation click → open source at page/block with highlight #72).
• The remaining viewer change — highlight the supporting span rather than the chunk's block union — is part of [Feat] Exact-passage citation: the model cites source spans, not chunks #155, not a new viewer.

Deliberately deferred

• v1.6: [Feat] Export a notebook, answer or note with its citations intact #159 export with citations preserved; [Feat] Cross-notebook source reuse (library-level sources) #99 cross-notebook source reuse; [Feat] Multiple chat sessions per notebook #97 multiple chat sessions; [Feat] Model connection diagnostics and first-run readiness #100 model connection diagnostics.
• Not scheduled: audio overview, mind map, flashcards, quiz, slides.

Stretch / orthogonal

• [Feat] Implement the Knowledge MCP server #80 Knowledge MCP server is in the v1.5 milestone because it was moved up at the maintainer's request, but it is not part of this theme and is not on the release critical path. It is labelled stretch and runs last, after KnowledgeQueryApi can be separated from Electron.

Exit criteria

• Citation quote and highlight are span-accurate on the [Feat] RAG eval harness: dataset format, runner, metrics #75 eval set, with no precision regression against the frozen v1.4 baseline.
• Citation coverage and unsupported-sentence rate are measured and visible.
• A user can scope a question to selected sources and see which were used.
• A failed reindex never destroys the previous usable index.
• Nothing in the epic requires a network call beyond the configured model endpoint.

[mrsibe]

v1.5 is complete — 12/12 issues closed, milestone v1.5 open=0.

Delivered:

• [Refactor] v1.5 architecture prep: freeze the retrieval, ingestion and citation seams #160 architecture prep: retrieval/ingestion/citation seams frozen (refactor(retrieval): freeze the v1.5 retrieval, ingestion and citation seams #161)
• [Feat] Exact-passage citation: the model cites source spans, not chunks #155 exact-passage citation: the model cites source spans, not chunks (feat(citation): cite a source span, not the whole retrieved chunk #162)
• [Feat] Citation coverage: mark uncited, invalid and inferred sentences #156 citation coverage: uncited / invalid / inferred, no false "grounded" claim (feat(citation): measure citation coverage and mark unsupported statements #164)
• [Feat] Source scope: retrieve from the current or selected sources, persisted per session #94 source scope, per session, filtered before the KNN (feat(retrieval): scope a question to chosen sources, filtered before the KNN #165)
• [Feat] Retrieval explainability: snapshot what this answer retrieved and cited #157 retrieval explainability: a per-answer retrieval snapshot (feat(chat): record and show how an answer retrieved #166)
• [Feat] Ingestion runs: persistent pipeline state, retry, and non-destructive re-index #95 ingestion runs: persistent state, retry, and a re-index that cannot destroy the working index (feat(ingestion): record every indexing attempt and never destroy a working index #167)
• [Spike] Chunking experiments: size / overlap / heading-aware / parent-child #78 chunking experiments: adopted 1000/100, and corrected nDCG (it could exceed 1) (feat(eval): chunking experiments, corrected nDCG, and a 1000/100 default #168)
• [Feat] Global search across sources and notes, with distinct exact and semantic signals #96 a shared FTS index + global search with distinct exact/semantic signals (feat(search): a full-text index over chunks and a global search palette #169)
• [Spike] Retrieval experiments: BM25 / hybrid / RRF / reranker on a frozen chunk baseline #77 retrieval experiments: hybrid RRF reported as inconclusive against a saturated Recall@5; dense kept (feat(retrieval): fusion candidate layer, BM25/hybrid strategies, and the retrieval experiment #170)
• [Feat] Implement the Knowledge MCP server #80 the Knowledge MCP server, read-only stdio via the v2 SDK's serveStdio (feat(mcp): serve the library over read-only stdio MCP #171)
• [Feat] Batch and folder import #98 batch and folder import, as a snapshot with honest counts (feat(import): batch and folder import, as a snapshot with honest counts #172)
• [Feat] Folder as a live source: watch, auto re-index, and mark stale #158 watched folders: keeps itself current, and never deletes a source (feat(watch): a watched folder keeps itself current, and never deletes #173)

Exit criteria met: citation quotes and highlights are span-accurate with coverage measured; a question can be scoped to chosen sources and each answer snapshots what it retrieved; a failed re-index leaves the previous usable index intact; nothing in the epic needs a network call beyond the configured model endpoint.

Carried to v1.6 (#159 export, #99 cross-notebook sources, #97 chat sessions, #100 diagnostics).