# research/ — Quarto book source

This directory is the **single canonical source** for the public research e-pub.
It is a [Quarto](https://quarto.org/docs/books/) `book` project that renders three
formats from one source tree: an HTML site, a PDF (TinyTeX/LaTeX), and an EPUB.

- **Config**: `_quarto.yml` — book project, formats, chapter list.
- **Theme**: `theme.scss` — the monochrome (black / white / grey) research-notebook
  palette (added in F-346 TASK-2957).
- **Build & deploy**: automated by `.github/workflows/research-publish.yml` (F-348),
  which renders all three formats and deploys the HTML to Cloudflare Pages on every
  change under `research/**`. There is no manual mirror step.

To build locally (requires Quarto + TinyTeX installed):

```bash
quarto render research
```

## Authoring rule — link only in-book, or write prose

The CI link-check (lychee, in `.github/workflows/research-publish.yml`)
fails the deploy on any broken link in the **rendered** book. Because the book
publishes only what's under `research/`, a chapter must **only** link to:

- another in-book chapter (e.g. `../research-platform/02-end-to-end-pipeline.md`), or
- an appendix / library page (`../appendix/*.qmd`, `../library/index.qmd`).

For anything **outside** the book — `docs/…`, `src/…`, `backlog/…`, `architecture/…`,
CLAUDE.md, config/DB/SPA paths, or a local paper `.pdf` — write **prose or inline
code** (`` `docs/research/foo.md` ``), or link the paper's **external source URL**.
A link whose target escapes the book (an `../../docs/` or `../src/` path) resolves on
disk but 404s in the deployed book and will bounce the Cloudflare deploy. (The `appendix/` chapters are the one exception —
they verbatim-`{{< include >}}` canonical `docs/` files whose internal links can't
resolve in-book, so they're excluded from the check.)

Not to be confused with `scripts/research/` (Python research scripts) or
`docs/research/` (internal findings) — both are unrelated to this book.

See the parent epic `docs/epics/research-epub-publishing.md` (in the main repo, outside this book).