# Inkhaven 1.4.5 — Bibliography & citations

_inkhaven compiles to Typst, which has a real bibliography engine — SOURCES-1 wires the two
together. Keep your references as structured entries inside the project, cite them in prose with
Typst's `@key` syntax, and at Book assembly inkhaven writes a `sources.bib` and appends
`#bibliography(...)` so `typst compile` renders the reference list and resolves every citation.
No external reference manager, no new content type, **no new dependencies** — the bibliography
lives in the project, versioned alongside the manuscript._

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

## A home for your sources

A new **Sources** system book holds citations as **HJSON paragraphs** (the editor highlights them
as HJSON — no new content type). Create a user book and inkhaven auto-creates a matching Sources
chapter, seeded with one placeholder entry so the schema is in front of you:

```hjson
{
  key: smith2024
  entry_type: article
  author: Smith, Jane
  title: On Things
  year: 2024
  journal: Journal of Things
}
```

The only required field is `key`; keyless drafts are skipped at compile time. Cite keys follow
Typst's grammar (`smith2024`, `doe:2023b`, `nguyen-1999`). Numbers may be unquoted (`year: 2024`)
— inkhaven coerces them. Three ways to author: press **`P`** under the Sources book (the title
becomes the cite key, body pre-seeded), bulk-import BibTeX, or copy the placeholder.

## Cite in prose, render at assembly

Write `@key` wherever you want a citation, exactly as in Typst. Forget a key? In the editor press
**`Ctrl+V @`** (the citation sigil) to open the **cite picker** — a fuzzy list of every defined
entry (`@key   year · author — title`); type to filter by key / author / title, `↑↓` select,
**Enter** inserts `@key`. (E-mail addresses are not mistaken for citations.)

At Book assembly — **`Ctrl+B A`** or `inkhaven build` — inkhaven collects the entries, writes
`<artefacts>/<book>/sources.bib`, and appends `#bibliography("sources.bib", style: "ieee")` to the
root `.typ`. `typst compile` then resolves your `@key` citations and renders the reference list.
The assembly status reports the count: `bibliography: N citation(s) -> sources.bib`.

## Validate before you build

**`inkhaven sources check`** scans your prose for `@key` tokens and verifies each is defined —
reading the same files assembly compiles, and **exiting non-zero** on any undefined key, so it
slots into a pre-build step or CI:

```sh
inkhaven sources check                       # all books; exit 1 on undefined @key
inkhaven sources check --book-name "My Novel" --json
inkhaven sources list                        # what's defined
inkhaven sources import refs.bib --book-name "My Novel"   # BibTeX → HJSON entries
```

The BibTeX importer is dependency-free: braced / quoted / bare values, balanced nested braces,
`@comment` / `@string` / `@preamble` skipped, biblatex `date → year`, `journaltitle` / `issue`
aliases — the format Zotero, JabRef, and Google Scholar export. Duplicate keys are skipped.

## One bibliography or many

The `sources:` config block:

```hjson
sources: {
  all: true                 // every entry → every book's sources.bib
  bibliography_style: ieee  // any CSL style Typst accepts (apa, mla, chicago-author-date, …)
  auto_bibliography: true   // append #bibliography(...) automatically
}
```

Set `all: false` to scope citations **per book** — only the Sources chapter named after the
assembled book is collected, so a two-manuscript project keeps two independent bibliographies.
`sources check` and the cite picker honour the same scope.

## From a script

Four read-only `ink.sources.*` Bund words (all `store_read`, default-allowed), reading from disk
so the scripted view matches what assembly compiles:

```
ink.sources.list     ( -- list )    every entry as { key, type, author, title, year, chapter }
ink.sources.get      ( key -- dict | NODATA )   one entry, all fields
ink.sources.check    ( -- list )    undefined @key citations as { key, book, paragraph }
ink.sources.bibtex   ( -- string )  the compiled BibTeX for all entries
```

Authoring stays in the CLI and TUI — Bund reads the bibliography, it never rewrites your sources.

## Notes

- **Existing projects** gain the Sources book on first open after upgrade (the system-book
  order-bump handles the insertion; one-time, idempotent). Books created before the upgrade get
  their Sources chapter on next provisioning.
- Built entirely on the existing `.typ` + DuckDB + serde-hjson stack — **no external app/binary
  deps; no new runtime crates.** New tutorial 89; `sources` CONFIGURATION block; `Ctrl+V @` in
  KEYBINDING. Tests 1882 → 1897.
