# Notebook export

## Formats produced

Export builds one coherent snapshot of the project + page results (or several
snapshots for a multi-notebook anthology), then writes the selected formats:

| File | Role |
|------|------|
| `notebook.transcribe.json` | Portable structured notebook (`format: transcribe.notebook`) — single-notebook exports |
| `bundle.transcribe.json` + `notebooks/<slug>/…` | Multi-notebook JSON index + per-notebook JSON |
| `notebook.md` | Markdown derived from effective text |
| `notebook.txt` | Plain text derived from effective text |
| `notebook.html` | Styled HTML (typography from export options) |
| `notebook.epub` | EPUB ebook (requires `ebooklib` / `transcribe[export]`) |
| `notebook.pdf` | Text PDF via PyMuPDF |
| `export.manifest.json` | Checksums, options, and file list for the bundle |

Default destination is the project `exports/` directory unless overridden (CLI dest / `TRANSCRIBE_EXPORT_DIR`).

## `content_revision` and `bundle_revision`

Every export bundle **must** stamp revision identity from the same frozen
snapshot(s) used to build all formats — not a later reload.

| Artifact | Where |
|----------|-------|
| `notebook.transcribe.json` | top-level `content_revision` (hex) |
| `export.manifest.json` | `content_revision` (single) or `bundle_revision` (anthology); always includes `bundle_revision` and `notebooks[]` |
| `notebook.md` | HTML comment header `<!-- transcribe.content_revision: <hex> -->` |
| `notebook.txt` | first line `# transcribe.content_revision: <hex>` |
| `notebook.html` | visible revision meta + same hex |
| `notebook.pdf` | PDF metadata `subject` includes the revision hex |
| `notebook.epub` | DC description includes the revision hex |

For a single notebook, `bundle_revision` equals the hash of that notebook’s
`(project_id, content_revision)` pair. Typography and other presentation
options **do not** participate in `content_revision` / `bundle_revision`.

## Export options and profiles

Workspace subtree `export` (see [workspace-settings.md](workspace-settings.md))
and profile target `export` control formats, page-break mode, date/blank
inclusion, title page, and typography (body font/size, line height, paragraph
spacing, margins, heading scale).

Builtin profiles: `default`, `readable`, `compact`, `large_print`.

## Multi-notebook anthology

When multiple notebooks are selected, human-readable formats concatenate parts
in selection order (each notebook is a part; pages remain sections inside).
JSON is emitted per notebook under `notebooks/<slug>/` plus
`bundle.transcribe.json`.

## `transcribe.notebook` JSON

- `format` must be `"transcribe.notebook"`
- `schema_version` must be `1`
- Includes `content_revision`, application version, project metadata, source summaries, and ordered pages
- Per page: order (`global_index`), status, effective/raw/edited text, fingerprints, provenance, tags/dates as present
- Optional additive `tag_catalog` snapshot (list of `{tag_id, slug, label, color, …}` for slugs used in the notebook). Legacy readers ignore it. Label/colour changes do **not** participate in `content_revision` (that hash uses page tag slugs only). Catalog contract: [tag-catalog.md](tag-catalog.md)
- Page date fields are always emitted together: `date`, `date_approved`, `date_source` (canonical triples; undated ⇒ `date: null`, `date_approved: true`, `date_source: null`)
- **Legacy readers** may ignore unknown keys (`date_approved`, `date_source`, `content_revision`) and continue to use `date` alone
- **Must not require absolute filesystem paths** in the interchange payload

## `transcribe.export-manifest`

- `format` must be `"transcribe.export-manifest"`
- `schema_version` must be `1`
- Includes `application_version`, `project_id`, `project_updated_at`, `content_revision`, `bundle_revision`, `notebooks`, optional `export_options`, `files`, and per-file `sha256`

## `transcribe.export-bundle`

Multi-notebook index (`bundle.transcribe.json`):

- `format` must be `"transcribe.export-bundle"`
- `schema_version` must be `1`
- Includes `title`, `bundle_revision`, and `notebooks[]` with per-part paths

## Snapshot semantics

All selected formats are derived from the same frozen load(s) of `project.json`
+ page results. Writers stage into a temporary directory under the destination,
then promote atomically so a failed export does not leave a mixed old/new set.

## Future consumers

A future TranscriptX adapter may consume `transcribe.notebook` after TranscriptX 1.0. Prefer `content_revision` when present. That seam is product/architecture guidance only today: [INTEGRATION_SEAM.md](../INTEGRATION_SEAM.md).