# Inkhaven 1.5.0 — Research Assistant

_Your manuscript stands on a foundation of facts — the geography that must stay consistent, the physics
of an invented world. In Inkhaven those live in the **Facts** system book, the ground truth the
world-checker, the Book-scope RAG chat, the Inner family, and the Mythology library all draw on. But
populating it meant leaving the writing environment. **`inkhaven research`** closes that loop: a
separate, full-screen TUI for AI-assisted research that transfers **verified** findings straight into
the Facts / Notes corpus — with a confirmation step on every insertion. **No new runtime crates.**_

_Plan: [RESRCH-1_PLAN.md](../PROPOSALS/RESRCH-1_PLAN.md)_

## A separate research screen

`inkhaven research [--thread <name>]` launches its own TUI — its own layout, event loop, and keymap,
sharing only the project's on-disk state. Three panes: the **Facts tree** (left 40 %), a **streaming
RAG chat** (right 60 %), and a two-line **query prompt**. `Tab` cycles focus; **`F10`** cycles the RAG
mode (Facts+Full / Facts only / Full only); **`Ctrl+B h`** shows a full quick reference; `Ctrl+Q`
quits from anywhere. Colours follow your `theme:` config.

Ask a question and the answer streams in, **grounded by your Facts book** — retrieval reuses the
existing book-scoped retriever, scoped to Facts, plus up to three **pinned** nodes (`Ctrl+P`) that are
always in context.

## Turning research into facts — reviewed, every time

- **`/fact "instruction" [→ path]`** distils the last response into one titled fact (a second LLM call,
  **in your project's language**) and opens an **editable confirmation overlay** — edit the title and
  body, `Ctrl+S` to insert, `Esc` to discard. An empty body is refused. Inserted facts re-embed
  immediately, so they're instantly available to `/diff`, the writing-mode RAG, and every Facts consumer
  — no rebuild.
- **`/note "…"`** does the same into the **Notes** book, preserving a speculative voice.
- **`n`** in the tree types a fact by hand.

## Checking — before and after

- **`/diff`** — the most similar facts already in your corpus (spot a near-duplicate before adding one).
- **`/verify`** — pulls the checkable claims (years, titles, quantities, names) and self-assesses each
  HIGH / MEDIUM / **⚠ LOW** confidence.
- **`/factcheck`** — a post-hoc, multi-call audit of the **whole corpus**: every fact judged for
  factual accuracy, then the full set checked for facts that **contradict each other**.
- **`/chain a → b → c`** — a sequential pipeline, each step feeding the next. Plus `/goto`, `/rag`,
  `/clear`, `/save`.

## A first-class tree

The Facts tree edits on par with the main editor and Outline: `R` rename, `c`/`s` new
chapter/subchapter, `-`/`D` delete, `K`/`J` move, and `y`/`x`/`p` copy/cut/paste across parents.

## Threads

Named, resumable sessions under `.inkhaven/research-threads/<slug>.json` — queries, insertions, pins,
and RAG mode persist and resume. A picker for >1 thread; `--list-threads` and `--export-thread`
(table/json/md) are non-interactive. `↑`/`↓` recall prompt history.

## Notes

- **No `facts.duckdb`** — the RFC assumed one, but facts are paragraphs in the Facts book indexed by the
  shared vector store; the assistant reads that, and inserts re-embed through the canonical path. The
  RESRCH-1 audit also corrected the streaming model (the writing TUI's synchronous crossterm loop +
  `spawn_chat_stream`, **not** `tokio::select`), the real store primitives (`create_node` +
  `update_paragraph_content`, `find_by_path`), and the reuse of `book_rag::retrieval`.
- **No new runtime crates; no new system books; no new `NodeKind`.** One sidecar dir
  (`.inkhaven/research-threads/`), one `research:` config block. New tutorial 103. Tests 2,146 → 2,177.
- Web search and document import are deferred to RESRCH-2. Costs are a coarse, marked `~` estimate that
  informs, never blocks. Every insertion requires explicit confirmation; nothing edits your prose.
