Research|Interactive reader's editions — bundling each dive's text (design)

_meta

Interactive reader's editions — bundling each dive's text (design)

Last modified 23 September 2026 · view source

This is the design for bundling the text of the work into each corpus-dive folder as an enriched, marked-up Markdown file — so a finished dive carries not just the research index and dossier, but a draft of the work’s overview page and a draft of the work itself, ready to become an interactive reader’s edition on the site.

It is the worked-out successor to the deferred brainstorm note (project_dive_bundled_text_brainstorm, 2026-06-22). The pilot is The Great Sin (docs/research/1905-the-great-sin/).

The split: this is spec 1 of 2

The conversation produced two clearly separable pieces. This spec covers only the first.

The reason the split is safe: one durable file, two renderers. Everything the e-reader does is rendering. Underneath sits one thing the dive produces — the marked-up text plus the dossier. Two renderers read it: serve.py today (research preview) and the Eleventy e-reader later. The reader UI can grow for years and the content is never redone. So what we design and produce per dive is that one file, not the e-reader.

The north star (context, not scope)

tolstoy.life becomes a new interactive edition of Tolstoy’s works: a clean e-reader by default, with toggleable layers summoned from a side rail — wikilinks, the passages Tolstoy or his editors or the censor cut, edition and translation differences, modal info boxes on the entities. Spec 1 produces the content those layers render; spec 2 builds the reader (now specified as a serve.py prototype: 2026-07-03-interactive-reader-prototype-design.md).

Governing principle — Tolstoy’s voice, not the mainstream filter

The reading text, the overview page, and the dives all present the work in Tolstoy’s own terms — his voice, his version. Too many resources treat him as a specimen, filtering his words through the mainstream society’s vocabulary and values to explain what he “really meant.” We don’t.

The anti-example (Standard Ebooks’ overview of The Kingdom of God Is Within You): “the most influential work of Christian anarchism… if it didn’t itself claim to merely be pointing out Christian anarchism as the plain meaning of the gospels.” It reaches for a label Tolstoy refused, notices he’d refuse it, and applies it anyway. Exactly the failure to avoid.

This is already the dives’ rule (corpus-dive-ground-in-primary-not-mainstream): lead with Tolstoy’s / Biryukov’s / Chertkov’s words; mainstream scholarship is contrast to read critically, never a baseline to confirm. The guardrail that keeps it honest cuts both ways: present what he wrote in his terms — neither softened by mainstream labels nor sharpened past what he actually said (ingestion-accuracy-both-directions).

Where the text lives — works/, not wiki/

The site already has the destination in skeleton:

website/src/works/<mainCategory>/<subcategory>/<work-slug>/
        ├─ Work-Title.md     ← the record + overview page (big schema frontmatter)
        └─ text/             ← the work's enriched text (CLAUDE.md already reserves works/**/text/)

wiki/ is for the entities the text points at — persons, concepts, places. The work itself is never a wiki page. The dive folder is a staging area: we draft the overview body and the text markdown inside docs/research/<dive>/, then promote both into works/.../ at ingestion — the same research → human-in-the-loop ingest discipline the dives already use.

Fix needed: CLAUDE.md currently calls works/**/text/ “source text, do not modify.” That wording is wrong for this design — the reading text is an enriched reader’s edition, edited on purpose (wikilinks, cut-markers). The unaltered archive is primary-sources/. Reword the CLAUDE.md line to “don’t corrupt the words,” not “no markup,” when this lands.

What a dive additionally produces

Three deliverables, staged in the dive folder:

  1. The enriched text — one file per version. A work has several versions of the same text: the Russian (Tolstoy’s original, from the corpus), the 1905 English (the period translation made in his lifetime, where a public-domain one exists), and a machine English (fresh, neutral). Each version is its own standalone file (<slug>.ru.md, <slug>.en-1905.md, <slug>.en-machine.md) so two can sit side by side in a split-view later and the Russian is never buried under the English. All version files share the same section anchors (the work’s own structure — Great Sin is intro + I–IX) so the columns line up. The editorial marks and wikilinks are written into each version in its own language — the Russian carries the byte-true variant from extracts/, the English carries a labelled machine rendering of it — all derived from the one dossier, not hand-duplicated. Default version the reader opens: the 1905 English where it exists, machine English otherwise, with Russian one click away.
  2. The overview-page draft — the reader-facing “about this work” page, distilled from the dive’s index.md (phase 1: mostly as-is, with the research scaffolding — coverage, needs-review, methodology — trimmed off). Dense with fact, lean on opinion, in Tolstoy’s terms (see the governing principle). Progressive disclosure, like the e-reader: a light orientation first, the detail beneath. The dossier’s workRecord supplies the schema frontmatter; this is the prose around it. This page is the work’s node in the graph — see “The work’s page” below.
  3. The machine-translation pass — a one-pass English translation, labelled “machine, unverified,” serving as the machine-English version and as the neutral third reference for the translation diagnostic. Optional per work; see Machine translation below.

The canonical edition (the spine)

Two different roles hide under “which version”:

The spine is the Russian PSS established text — always. Four reasons, all pointing the same way:

  1. His voice. The governing principle: the Russian is what Tolstoy wrote; every translation is one filter removed. The canonical text has to be his words.
  2. The marks are defined against it. A cut is a passage absent from the PSS established text; a softening is a change to it. The Russian PSS is the ruler everything else is measured with; translations are projections of it.
  3. Translations are plural and each is biased — nothing derivative can be canonical, by definition.
  4. The PSS editors already did the edition-scholarship. Where two Russian editions differ (Русская мысль vs «Свободное слово»), they established the base text and recorded the other as variants. We defer to that — we don’t re-adjudicate which Russian edition is “right.”

So translations never compete for spine; they are derived versions measured against it. Among multiple Russian editions, the PSS established text is the spine and the others are edition-diffs against it. The spine’s chapter structure also sets the section anchors every version aligns to in split-view. This doesn’t fight the English mission: English is how we serve the work; Russian is what it is.

The encoding vocabulary

The marks are CriticMarkup — an existing plain-text standard for editorial change-tracking (deleted / inserted / changed / commented text) — plus the project’s existing [[wikilink]]. Nothing invented. The marks map one-to-one onto the textual facts the dive already extracts into the dossier.

Mark CriticMarkup Encodes Renders as
Excision … A passage cut before print (Tolstoy, an editor, or the censor) Ghost block at the seam
Insertion … A passage added in a later draft/proof Revealed addition (the text growing)
Softening / edition diff oldnew A word/phrase changed between draft and print, or between two editions Dotted printed word; reveal shows the other reading
Note … The editorial fact — who, when, why The modal/info card
Wikilink [[Entity]] A person/concept/place Toggleable link → entity modal

Three conventions on top:

Worked example (real Great Sin material; English wording illustrative):

The poverty of the masses springs fromis connected withChertkov softened this, 8 Jul 1905: the evil itself springs from a deeper evil, human egoism this one cause.

Just as the slave-owner of old re-enacted his crime each day he held men as property, so the
landowner renews this sin each day he holds the earth.var. 8, cut at Chertkov's suggestion

the single tax that [[Henry George]] proposed.

The serve.py render pass

serve.py uses Python-Markdown, so the rendering is mostly off-the-shelf extensions, not custom parsing:

Plus a minimal focus-mode reading template and CSS so the layers are visible and toggleable in the preview. This is preview-grade only — the real rail, theming, and bookmarks are spec 2.

Default reading state is bare. The marks live in the file, but the default view shows none of them — clean focus mode, pleasing typography, the text alone. Wikilinks, footnotes, cut-reveals, and the version switcher are all opt-in, summoned by the reader. For spec 1 this is free: default CSS hides the marks; a toggle reveals them.

Machine translation

Fidelity and guardrails

How it’s built and run

The work’s page (and wiki scope)

One page, not two. The overview page is the work’s node in the graph — there is no separate wiki/ stub for the work. [[The Great Sin]] resolves to the overview page; backlinks collect there.

[[The Great Sin]] ──► works/non-fiction/.../The Great Sin.md   (type: work — the node itself)
                                  │  its text links out ▼
                                  └─► wiki/Henry George.md       (type: person — an entity)

wiki/ stays for the entities a text points at — people, concepts, places. A work is a first-class node too, but it lives in works/ because it carries the schema record and the reading experience (versions, library, progress) an entity never has. Give the overview a type: work so the graph can tell a work-node from a person-node (the Tolstoy-Lab already found it wants that 13th type) — but type is a label, not a second home. A separate wiki/the-great-sin.md would just be two pages fighting over which is “the work,” and they’d drift.

The reader edition embeds [[wikilinks]] (toggleable) and the dive proposes the works/ record (as it already does). It does not create the wiki entity pages — those stay the separate human-in-the-loop ingestion step. Embedded wikilinks may point at not-yet-created entity pages; that’s expected and marks future work.

Out of scope (spec 2 or beyond)

Settled in this brainstorm

Left for the implementation plan