publish-webtoon

name

publish-webtoon

description

Assemble, export, rebuild, and validate final vertical-scroll webtoon episodes as sequential PNG files under the series and episode folders in published/webtoon. Use when the author asks to publish, package, render, join, split, export, regenerate, or validate a webtoon episode; when checking 690px canvas width, 10,000px chunk limits, safe seams, section order, transition gutters, numbering, color mode, hashes, or final output integrity.

Publish Webtoon

Operating Contract

Turn final directed section sources into delivery PNGs. $direct-webtoon must already have directed the storyboard/images (blocking, pose, expression, camera, background, effects) and final vertical layout under one approved direction.md. Do not ask an image model to make an entire 10,000px episode and do not invent story art during publication. The publisher only scales, adds declared deterministic gutters, assembles, splits at approved direction seams, hashes, and validates.

Treat episodes/, canonical Markdown, and assets/ as source. Treat published/ as generated output. Never hand-edit a published PNG. Rebuild after correcting source.

Before bundled scripts, call load_workspace_dependencies, set PYTHON to the returned executable, and use locked uv run --frozen --python "$PYTHON" python ... commands below.

Workflow

1. Read Publication Context

Read:

• AGENTS.md, project.md, and style/publish-profile.md;
• the target episodes/ep.NN/episode.md, storyboard.md, and final approved direction.md;
• episodes/ep.NN/sections/*.md frontmatter;
• final section source PNGs only as needed for verification.

Do not load every image into model context. Let the script stream them. Inspect visual section seams or output previews only when diagnosing or completing visual QA.

2. Preflight

Require:

• series_slug, 690px canvas, chunk target/max, and minimum episode height in project.md;
• gapless section records beginning at 001.md;
• direction.md with status: final, approval.status: approved, and section order matching the records;
• every section referencing that direction with direction_approved: true;
• every source path repository-relative, outside published/, and existing;
• status: final and seam_safe: true for every published section;
• source width suitable for deterministic normalization to 690px;
• section height not exceeding the output maximum;
• transition kind none, solid, or gradient with valid colors;
• no source section repeated or omitted.

For every section, the publisher invokes $direct-webtoon's final validator with --require-record-final. Publication therefore blocks on the approved shared artwork anchors, previsualization/art/style-drift QA, final layout approval, section/episode direction links, source geometry, and safe seams—not merely on a PNG path in frontmatter.

Run the story validator first:

uv run --frozen --python "$PYTHON" python .agents/skills/webtoon-story-telling/scripts/check_webtoon.py \
  --project-root .

Warnings require review; errors block publication.

3. Publish

Run from the repository root:

uv run --frozen --python "$PYTHON" python .agents/skills/publish-webtoon/scripts/publish_webtoon.py \
  --project-root . --episode 1

The script:

1. loads section records in numeric order;
2. flattens each section to opaque sRGB/RGB at 690px width;
3. appends only the declared solid/gradient gutter between sections;
4. keeps every section-plus-transition block atomic;
5. starts a new output before the next block would exceed 10,000px;
6. writes a staging folder and validates it before replacing generated output;
7. creates gapless 001.png, 002.png, ...;
8. records source/output SHA-256, dimensions, total height, and section order in the series-level manifest.

The final chunk may be shorter. Never pad a final chunk merely to reach 10,000px; episode total height is the meaningful minimum.

4. Validate

Validate existing output without rebuilding:

uv run --frozen --python "$PYTHON" python .agents/skills/publish-webtoon/scripts/publish_webtoon.py \
  --project-root . --episode 1 --validate-only

Require exact width, height at or below the configured maximum, RGB mode, valid PNG, gapless names, no extra episode-folder files, minimum total episode height unless canonically short-form, and hashes matching the series manifest.

5. Visual QA

Deterministic validation cannot decide whether a seam feels natural. Review sequential outputs at normal width and as a reduced scroll preview. Confirm:

• no face, body, balloon, text, required action, or panel interior is cut;
• declared gutters preserve rhythm and color continuity;
• direct continuations align;
• no accidental blank band, duplicate section, missing section, scale jump, or color-mode shift appears;
• dialogue and SFX remain legible.

Repair canonical section art or metadata and republish. Do not paint over final output.

Failure Handling

• Stop on missing/non-final sources, unsafe seams, malformed metadata, duplicate numbers, over-tall atomic sections, invalid color, path escape, or validation failure.
• If one section exceeds the maximum, return to $webtoon-story-telling and split it at a narratively safe gutter; never slice through it automatically.
• If the total is below 10,000px, extend/restructure the episode source or explicitly set allow_short_episode: true in canonical project/episode metadata.
• If a seam needs painted continuation, create that bridge as a reviewed source section with $imagegen; the publisher only performs declared simple fills.

Completion Report

Report the absolute episode output directory, series slug, episode number, output file count, dimensions, total height, source section count, and manifest path. Separate generated ignored output from canonical changes. Do not upload or distribute unless explicitly asked.