scholarly-edition

name	scholarly-edition
description	Create a DOI-ready scholarly edition of a translated book. Use when asked to publish, create an edition, mint a DOI, or prepare a book for scholarly publication. Generates front matter, creates versioned editions, builds EPUBs, and mints DOIs via Zenodo.

Scholarly Edition Workflow

Create a complete, citable scholarly edition of a translated historical text with DOI.

Prerequisites

Before starting, verify the book has:

• Completed OCR for all pages
• Completed translations for all pages
• Book metadata (title, author, language, publication date)

Authentication: Steps 2, 3, and 5 require admin authentication. When running as a Claude Code agent, requests go through the local dev server or use session cookies automatically. For manual curl commands, you need an authenticated session.

Workflow Steps

Step 1: Gather Book Information

First, get the book ID and check its readiness:

# Get book details and page statistics
curl -s "https://sourcelibrary.org/api/books/BOOK_ID" | jq '{
  title: .title,
  display_title: .display_title,
  author: .author,
  language: .language,
  published: .published,
  pages_count: .pages_count,
  pages_translated: .pages_translated
}'

The book API returns pages_count and pages_translated as cached counts. Confirm pages_translated equals pages_count before proceeding. For detailed page-level text, use /api/books/BOOK_ID/text?content=translation.

Step 2: Generate Front Matter

Generate the scholarly Introduction and Methodology sections:

curl -X POST "https://sourcelibrary.org/api/books/BOOK_ID/editions/front-matter" \
  -H "Content-Type: application/json" \
  -d '{}'

This creates:

• Introduction: Historical context, author biography, work significance
• Methodology: OCR process, translation approach, editorial conventions

Save the response to use when creating the edition.

Step 3: Create the Edition

Create a versioned edition with the generated front matter:

curl -X POST "https://sourcelibrary.org/api/books/BOOK_ID/editions" \
  -H "Content-Type: application/json" \
  -d '{
    "version_label": "First Edition",
    "license": "CC-BY-4.0",
    "changelog": "Initial scholarly edition with AI-assisted translation.",
    "contributors": [
      {"name": "Source Library", "role": "editor", "type": "ai"},
      {"name": "ORGANIZATION_NAME", "role": "editor", "type": "human"}
    ],
    "front_matter": {
      "introduction": "INTRODUCTION_TEXT",
      "methodology": "METHODOLOGY_TEXT",
      "generated_at": "ISO_DATE",
      "generated_by": "gemini-3-flash-preview"
    }
  }'

Note the returned edition_id for the next step.

Step 4: Verify Scholarly EPUB

Test the scholarly EPUB download:

curl -sL "https://sourcelibrary.org/api/books/BOOK_ID/download?format=epub-scholarly" \
  -o /tmp/scholarly-test.epub

# Check file size
ls -lh /tmp/scholarly-test.epub

The EPUB should include:

• Title page with DOI badge (placeholder until minted)
• Copyright and license page
• Introduction
• Methodology
• All translated pages with facsimile images
• Summary (if indexed)
• Glossary (if vocabulary indexed)
• Index (if keywords/concepts indexed)
• Colophon with citation information

Step 5: Mint DOI via Zenodo

Mint a permanent DOI for the edition:

curl -X POST "https://sourcelibrary.org/api/books/BOOK_ID/editions/mint-doi" \
  -H "Content-Type: application/json" \
  -d '{"edition_id": "EDITION_ID"}'

This will:

1. Create a Zenodo deposit
2. Upload the translation text
3. Set metadata (title, creators, license, keywords)
4. Publish and mint the DOI

The response includes:

• doi: The permanent DOI (e.g., 10.5281/zenodo.12345678)
• doi_url: The resolvable DOI URL
• zenodo_url: Direct link to Zenodo record

License Options

Valid SPDX license identifiers:

• CC-BY-4.0 - Attribution (recommended for scholarly work)
• CC-BY-SA-4.0 - Attribution-ShareAlike
• CC-BY-NC-4.0 - Attribution-NonCommercial
• CC-BY-NC-SA-4.0 - Attribution-NonCommercial-ShareAlike
• CC0-1.0 - Public Domain

Version Numbering

Follow semantic versioning:

• 1.0.0 - First published edition
• 1.1.0 - Minor corrections, improved translations
• 2.0.0 - Major revision, new translations

Output Summary

After completion, provide:

Field	Value
Book	[Title]
Edition	[Version] - [Label]
Pages	[Count] translated
DOI	[DOI]
DOI URL	[URL]
Zenodo Record	[URL]
License	[License]
EPUB Download	?format=scholarly

Troubleshooting

Zenodo Validation Errors

• Check that all required metadata fields are present
• Ensure license is a valid SPDX identifier
• Verify creators array is not empty

Missing Front Matter

• Run the front-matter API first
• Check that the book has sufficient content for AI generation

EPUB Issues

• Verify all page images are accessible
• Check that translations exist for included pages