novel-delivery

Novel Delivery

Overview

Validate a completed novel project, assemble a single manuscript, and export themed PDF and EPUB deliverables, while producing clear failure reports.

The regular delivery workflow must use the scripted exporter. The agent is responsible for triggering the export and validating the results; manuscript assembly and default PDF rendering are performed by the export script.

When to Use

The project status is draft_complete or delivery_blocked
All chapters have finished being written and passed review
The user wants to export the final manuscript
Latte PDF, Mocha PDF, and EPUB outputs are needed

Entry Gate

Before exporting, check:

00-project/workflow-status.md status is draft_complete or delivery_blocked
30-draft/chapter-plan.md
30-draft/chapters/ - all planned chapters exist
50-delivery/metadata.md
50-delivery/frontmatter.md
Local Pandoc availability
Local Node dependencies for this skill via npm install in the skill directory that contains this SKILL.md
A Chromium-compatible browser path for PDF printing
Chinese serif and sans font availability from the skill fallback lists

Only hard-block when the absence of something would make it impossible to produce the file at all.

The following quality-only issues should not block the export:

missing chapter reviews
chapter reviews marked 不通过
missing optional metadata fields
invalid or missing cover path

Record these issues as warnings, and continue exporting.

If 50-delivery/metadata.md or 50-delivery/frontmatter.md is missing:

copy the matching file from <skill-root>/templates/
fill the minimum required fields before export

Minimum required fields:

metadata.md: Title, Author, Language
frontmatter.md: Book Title, Author, Rights, Summary

Project Root Identification

All paths in this skill should be treated as relative to the novel project root.

Before exporting, resolve the root directory according to the following rules:

if the current directory already contains 00-project/workflow-status.md, use it
otherwise, if the current directory contains exactly one child book directory with 00-project/workflow-status.md, use that child directory
otherwise, stop and report that the novel project root is missing or ambiguous

This covers the common <workspace-root>/<book-slug>/00-project/... workspace layout and avoids invalid blind directory searches.

If no Chromium-compatible browser is available, do not just give a generic environment error. The skill must:

detect the current platform
use a concise platform-specific browser install plan
prefer short, actionable browser setup guidance over complex TeX distribution repair
block delivery with concrete next-step commands if the browser path is unavailable

If this skill's Playwright dependency is unavailable, block delivery with a clear next action:

run npm install from the skill directory that contains this SKILL.md

Status Updates

Keep draft_complete or delivery_blocked
Only set it to delivery_in_progress
Do not manually change workflow-status.md to delivery_in_progress; just run export-book.mts, and the export script is responsible for switching the status after the precheck passes
Set to delivery_blocked
Only set it to delivery_complete

Scripted Manuscript Assembly

50-delivery/book.md is an exporter-generated intermediate file, not a manual authoring target.

The only supported assembly path in the regular delivery workflow is the export script. It assembles in the following order: 50-delivery/book.md：

50-delivery/frontmatter.md
Chapters from 30-draft/chapters/ in planned order

Do not manually edit book.md and treat it as the source of truth. Always regenerate from the approved chapter files.

In the regular export workflow:

do not manually concatenate frontmatter and chapter files
do not read every chapter body in order to build book.md yourself
do not reimplement the exporter logic in shell, PowerShell, or ad hoc Markdown assembly
inspect chapter files only as needed for preflight checks such as existence, planned order, and obvious delivery blockers

Only read the full chapter text when debugging the exporter itself, or when the user explicitly requests a content-level delivery review.

Required Metadata

Hard requirements before export:

title
author
language

Warn when the following are missing, but continue execution:

summary
keywords
publication date
output formats
cover path when used

metadata.md is a Markdown file intended for authors to fill in, not raw YAML read directly by Pandoc. The exporter extracts key-value pairs from this Markdown and generates a temporary YAML metadata file for Pandoc to use.

Export Command

Run the scripted exporter with Node from the workspace root or the novel project root:

node --experimental-strip-types <skill-root>/scripts/export-book.mts --project-root <workspace-or-novel-project-path>

This command is the default and required path for the delivery workflow. The agent should trigger this command rather than manually reproducing its assembly steps.

Default PDF export workflow:

assemble 50-delivery/book.md
generate Latte and Mocha HTML via Pandoc
print those HTML files to PDF with Playwright plus a Chromium-compatible browser
generate EPUB through Pandoc

By default, chapter order is parsed from 30-draft/chapter-plan.md , accepting the following two common formats:

explicit chapter ids such as chapter-01
Markdown headings such as ### Chapter 1

PDF export should produce:

50-delivery/output/<slug>-latte.html
50-delivery/output/<slug>-mocha.html
50-delivery/output/<slug>-latte.pdf
50-delivery/output/<slug>-mocha.pdf

Theme PDF export should verify:

Chromium-compatible browser availability
Chinese font availability
Non-empty output files
Latte is suitable for printing and light-screen reading
Mocha uses a full dark page theme for screen reading

EPUB export should verify:

Non-empty output file

Output Verification

After export, check:

50-delivery/output/<slug>-latte.html exists and is non-empty
50-delivery/output/<slug>-mocha.html exists and is non-empty
50-delivery/output/<slug>-latte.pdf exists and is non-empty
50-delivery/output/<slug>-mocha.pdf exists and is non-empty
50-delivery/output/<slug>.epub exists and is non-empty

If non-blocking issues are found, write them to 50-delivery/output/delivery-warnings.md。

If verification fails, the deliverable must not be marked as complete.

Failure Log

If export fails, write a concise report to 50-delivery/output/export-log.md including:

Attempted command
Error summary
Likely cause
Next fix to try
Platform-specific browser install command when the PDF renderer is missing

If pre-check or export fails:

set workflow status to delivery_blocked
stop immediately after logging the failure

If export succeeds but with warnings:

keep the generated deliverables
write 50-delivery/output/delivery-warnings.md
allow delivery_complete

Mandatory Export Steps

Must be executed before export (cannot be skipped):

Run the export script; do not manually assemble the manuscript
Explicitly check Pandoc availability
Export PDF using the Chromium print path
Assemble book.mdaccording to the script workflow, do not manually concatenate

Common Self-Persuasion

Excuse	Reality
"Just export once and see"	Before any deliverable is produced, the critical export checks must still pass.
"Missing some metadata only affects appearance"	Minimal metadata is required, but missing optional fields should be downgraded to warnings rather than blocking output.
"Most machines should have Pandoc installed"	Environment assumptions must be explicitly checked.
"I should read out all the chapters and assemble a `book.md`"	Manual assembly is prohibited in the standard delivery workflow; the export script should be used.
"Assembling `book.md` means the agent concatenates files itself"	In this skill, unless you are debugging the exporter itself, the assembly responsibility belongs to the script.
"To export PDF, I should first go fix `xelatex`"	The default PDF path is Chromium printing; unless the user explicitly requests LaTeX, do not waste context on TeX.

Next Steps

After delivery_complete , the entire workflow ends. The deliverable is located at 50-delivery/output/。