Context
During the #211 pilot, Claude created a good cartoon story plan but wrote plot-01.cuts.json in a custom planning schema instead of the schema the app actually reads.
Example failure pattern from the pilot:
- top-level
$schema, story, workflow, promptDefaults
- cut ids like
"c01"
shot instead of shotType
- nested
image.prompt, image.clean, image.final
- nested
text.narration, dialogue[].line, sfx: []
The current app expects the app/lib/cuts.ts schema:
version: 1
plotFile: "plot-01"
- numeric
cut.id
cut.shotType
cut.description
cut.dialogue[].speaker + cut.dialogue[].text
cut.narration, cut.sfx
cleanImagePath, finalImagePath, exportedAt, uploadedCid, uploadedUrl
overlays: []
Parent epic: #197. Blocks #211 pilot approval.
Task
Update the generated cartoon story instructions so agents create the exact app-compatible plot-NN.cuts.json format.
Files to inspect/update:
app/lib/generate-story-instructions.ts
app/lib/generate-story-instructions.test.ts
app/lib/cuts.ts
~/z-docs/PROPOSAL-plotlink-ows-webtoon-pivot.md only as planning reference if available
Requirements
- Add a concrete valid JSON example for
plot-01.cuts.json using the real schema from app/lib/cuts.ts.
- Make clear that agents must not invent alternate schemas or nested planning structures.
- Include explicit field naming guidance:
- use
shotType, not shot
- use numeric
id, not c01
- use
description, not image.prompt
- use
dialogue[].text, not dialogue[].line
- use string
sfx, not array sfx
- use
cleanImagePath / finalImagePath, not nested image paths
- Keep the clean-image-first and no-baked-text rules intact.
- Do not change fiction instructions.
Acceptance Criteria
- New cartoon
CLAUDE.md contains a valid cuts.json example matching validateCutsFile.
- Tests assert the cartoon instructions include the required schema fields and do not encourage the invalid pilot schema.
- Existing fiction instruction tests still pass.
npm run typecheck and relevant tests pass.
Public Safety
Do not include private story draft content, local paths, secrets, wallet data, auth tokens, or Claude session IDs in the issue, tests, or docs.
Context
During the #211 pilot, Claude created a good cartoon story plan but wrote
plot-01.cuts.jsonin a custom planning schema instead of the schema the app actually reads.Example failure pattern from the pilot:
$schema,story,workflow,promptDefaults"c01"shotinstead ofshotTypeimage.prompt,image.clean,image.finaltext.narration,dialogue[].line,sfx: []The current app expects the
app/lib/cuts.tsschema:version: 1plotFile: "plot-01"cut.idcut.shotTypecut.descriptioncut.dialogue[].speaker+cut.dialogue[].textcut.narration,cut.sfxcleanImagePath,finalImagePath,exportedAt,uploadedCid,uploadedUrloverlays: []Parent epic: #197. Blocks #211 pilot approval.
Task
Update the generated cartoon story instructions so agents create the exact app-compatible
plot-NN.cuts.jsonformat.Files to inspect/update:
app/lib/generate-story-instructions.tsapp/lib/generate-story-instructions.test.tsapp/lib/cuts.ts~/z-docs/PROPOSAL-plotlink-ows-webtoon-pivot.mdonly as planning reference if availableRequirements
plot-01.cuts.jsonusing the real schema fromapp/lib/cuts.ts.shotType, notshotid, notc01description, notimage.promptdialogue[].text, notdialogue[].linesfx, not arraysfxcleanImagePath/finalImagePath, not nested image pathsAcceptance Criteria
CLAUDE.mdcontains a validcuts.jsonexample matchingvalidateCutsFile.npm run typecheckand relevant tests pass.Public Safety
Do not include private story draft content, local paths, secrets, wallet data, auth tokens, or Claude session IDs in the issue, tests, or docs.