Knowledge Base & Retrieval

How v10r organizes the knowledge its chatbot answers from, and how it retrieves it. The integrating blueprint above layered-rag.md, graph-rag.md, and surfaces.md — read those for the per-layer detail; read this for the whole-system mental model and the honest map of what is wired versus scaffold.

This is a reference project. Wired-vs-scaffold honesty is the point. Several pieces below are designed and schema-backed but not running in production (the llmwiki pointer layer is empty; tier-3 graph is dormant for docs; some telemetry is fabricated). Marking that truthfully is the showcase — a RAG pattern library that lies about what it ships teaches nothing. The Phased roadmap at the end is designed, not built, past Phase C.

Terminology

Three names, one of which is not code.

The user's mental model is exact and worth stating plainly:

nRAG = a connector/pointer over raw-RAG. That is the llmwiki design — one curated TLDR per topic, each carrying chunk-id pointers down into the immutable rawrag layer. It is a recognized pattern (multi-vector / doc-summary / parent-doc retrieval), not an invention.

The model answers from llmwiki TLDRs by default and drills into rawrag chunks only for exact wording or claim verification. llmwiki is the answer surface; rawrag is the audit trail. See layered-rag.md.

Wired vs scaffold (the honest map)

What actually runs today, what is schema-backed scaffolding, and what is designed only.

The asymmetry is deliberate: the engine is mature; the food (corpus + curated pointer pages) is thin. That is the inverse of where the leverage is — see The recall safety net.

The corpus & chunking model (the "food")

Retrieval quality is bounded by chunk quality. Markdown becomes a two-level hierarchy:

• Parents (level = 'section') — heading-bounded sections. Stored with embedding = NULL so tier-1 never surfaces them; they exist only as tier-2 parent context.
• Children (level = 'paragraph') — embedded leaves, each linked to its parent via parent_id.

Every child carries a deterministic heading-breadcrumb context prefix — ${doc.title} › ${deepest heading} — prepended before embedding so a chunk pulled in isolation still knows where it sits. This is a cheap stand-in for Anthropic-style LLM contextual prep, which is deferred: per-chunk LLM calls are infeasible on a ~20-req/day free-tier ceiling. The breadcrumb is derived by scanning ATX heading lines, no model call.

Two corpora, one kernel:

The unified ingest door (the two-chunker divergence, resolved 2026-06-25). The docs corpus was historically fed by a Bun script that re-implemented chunking via the dependency-free markdown-split.ts — flat paragraph chunks, bare-title prefix, no parents. As of 2026-06-25, ingest-docs.ts reuses the app's pure planChunks() (rawrag/plan.ts), so both runtimes share one door: it writes section-parents (embedding = NULL) + paragraph-children (parent_id set, deterministic "<docTitle> › <deepestHeading>" breadcrumb prefix). Entities + Neo4j remain app-path-only.

Conversion is partial and quota-gated — not a defect. Live state 2026-06-25: 36 of 93 docs hierarchical, 57 still flat. The Gemini free tier caps embeddings at 1000 embed_content requests/day; the corpus is ~1586 chunks, so a full flat→hierarchical re-ingest spans multiple days. The re-ingest is resume-safe — INGEST_FORCE=1 / --force skips any doc that already has a level='section' chunk. This partial state does not degrade chatbot answers: the chatbot reaches tier-1 only, and tier-1 reads flat and hierarchical paragraph-children identically. Proven 2026-06-25 — a question answered from a still-flat doc (multi-client-core, 0 sections / 33 embedded paragraphs) returned a correct, cited answer. Hierarchical chunking is groundwork for future tier-2 surfaces (rag-demo / reranker), not the change that corrected the chatbot.

The system overview anchor (BUILT, browser-verified 2026-06-25). A single high-level kind='overview' llmwiki row (system-owned, deterministic 94-doc knowledge-map TOC) injected into every chatbot turn as a <project-overview> block. ingest-docs.ts writes it; getOverview/loadOverview are owner-aware (inArray(userId, ownerIds)); the orchestrator loads loadOverview([SYSTEM_DOCS_USER_ID], PROJECT_DOCS_COLLECTION_ID). Verified live: exactly one overview row (system-docs/project-docs, source_count = 94, embedded); grounding fires end-to-end (llmwiki:overview → search → context → generate). (source_count = 94 is the full manifest doc count; the 36/57/93 corpus figures above count docs with live chunks — one doc transiently sits in a soft-deleted gap when the daily embed cap is hit, self-healing on the next resume run.) This is the load-bearing fix for the original broad-question bug — and because it is a plain DB-row read with no embedding, it lands even when the embed quota is exhausted. Read-truncation hazard, fixed 2026-06-25: the stored body is 5000 chars but loadOverview truncates at read to OVERVIEW_MAX_TOKENS × CHARS_PER_TOKEN = 500 × 4 = 2000 chars. The TOC is section-ordered foundation › blueprint › stack, so the large blueprint section pushed the ## stack list past 2000 chars — "which stack does v10r use?" was truncated off before the model saw it (compounded by design: every clean stack enumeration — docs/stack/README.md, docs/stack/vendors.md, CLAUDE.md — is corpus-excluded, so retrieval alone can't surface it). Fix: buildOverviewBody(), extracted to the Vite-free, unit-testable src/lib/server/docs/overview-body.ts (imported back by ingest-docs.ts, same pattern as doc-filter.ts), now inserts a deterministic one-line Stack: summary right after the intro and before the TOC (~char 320, well inside the ceiling), names derived from the core stack subsection doc titles — no hardcoding. OVERVIEW_MAX_TOKENS is deliberately unchanged. The rest of the TOC still truncates; only the stack answer is rescued. Built + validated 2026-06-25; reaches the live anchor on the next post-quota-reset db:ingest-docs — the stored row is not yet rewritten (today's embed quota is exhausted).

Why README nav-hubs are excluded. Every docs directory has a README.md that is a navigation index — topic tables mapping files to topics (docs/README.md). Those are pointers, not prose; embedding them pollutes retrieval with link-lists that answer nothing. isBlocked drops every */README.md from the corpus.

The recall safety net

The pointer (llmwiki) layer must always run IN PARALLEL with flat retrieval. A summary can never gate recall.

This is the load-bearing principle of the whole design. The research consensus is blunt about the failure mode: a summary/pointer layer is the lowest-leverage lever and the highest-risk one, because "the summary hid the chunk" silently drops recall — the answer was in the corpus, but the curated page didn't point at it.

So flat retrieve() runs unconditionally underneath the pointer layer; results are deduped by chunkId and reranked (no second RRF pass). The flat net is the recall guarantee. llmwiki must not be promoted to the default answer surface until the lint job is scheduled and green — until then, the parallel flat path is what keeps recall honest. This is why the system-docs prefetch (live) matters more than the empty llmwiki layer.

Retrieval-strategy seams

The target query path, with each seam's build status. "A blank stage is a lie; a skipped stage is the lesson" — the showcase must emit every stage, marking unrun ones status:'skipped' rather than hiding them.

query
  → step-back query-transform   (PLANNED · gated on broad-query intent, quota-budgeted, identity-fallback)
  → per-tier retrieval          (BUILT · tier-1 live & chatbot-only; tiers 2/3 eligible for converted docs, unexercised by chatbot)
  → RRF fusion (k=60)           (BUILT · rarely fires multi-tier for docs today)
  → rerank                      (PLANNED · slots after fusion, deterministic/local fallback)
  → drill-by-id                 (BUILT · verbatim-ids rule, see layered-rag.md)
  → citation-verify             (BUILT · onFinish, quote/paraphrase/drifted)
  → eval                        (PLANNED · golden-set harness, RAGAS-style metrics)

Sequencing matters: step-back runs BEFORE embed (it rewrites the query); rerank runs AFTER fusion (it reorders candidates). Both are gated and fall back to identity so a quota-exhausted turn still answers. The orchestrator must be split along these seams before eval and rerank have a slot to live in — extracting the retrieval-strategy seam is the unblocking move. See Phased roadmap.

Data-model & contract notes

Summaries only — the detail lives in code and in the roadmap.

Tooling rationale

The research line throughout: fix the food, not the framework. Self-contained chunks, contextual prefixes, an overview anchor, README exclusion, hybrid BM25, step-back, a reranker, and a golden-set eval all outrank any amount of orchestration cleverness. The summary/pointer layer is the last thing to invest in, and only behind a lint net.

Phased roadmap

Everything past Phase C is DESIGNED, not built. Phase C landed and was browser-verified on 2026-06-25; it is migration-free (no db:push — every column already exists) and its only deploy action is re-running db:ingest-docs. The rest is captured here so the decisions don't evaporate.

Phase C — Foundation (BUILT + browser-verified 2026-06-25, migration-free)

The three quick-wins, independently the right foundation. Steps 2 + 3 share one orchestrator edit hotspot (the Promise.allSettled grounding block) and landed in one pass. All three are live — 5/5 functional probes green on 2026-06-25, with honest "I don't have that in the provided documentation" on out-of-corpus questions (no fabricated paths or numbers).

Beyond Phase C (designed, not built)

Open product decisions

Related

• layered-rag.md — the two-layer split, read path, tool contracts, catalog grounding, graph tenancy. The primary RAG doc.
• surfaces.md — chatbot vs deskbot; the one-kernel/two-profiles model.
• graph-rag.md — rawrag internals; the catalog :Resource seed; the hybrid pipeline.
• README.md — AI blueprint nav hub.