plotlink-ows 1.0.33 → 1.2.94

package/app/lib/generate-story-instructions.ts

@@ -0,0 +1,731 @@
+import fs from "fs";
+import path from "path";
+import type { AgentProvider } from "../routes/stories";
+
+function fictionInstructions(): string {
+  return `# Writing Instructions — Fiction
+
+> Auto-generated by PlotLink OWS. Do not edit manually.
+> For API endpoints and publish details, see ~/.plotlink-ows/CLAUDE.md.
+
+## Story File Structure
+
+\`\`\`
+structure.md    — Story outline, characters, and arc
+genesis.md      — Synopsis hook (~1000 chars)
+plot-01.md      — Chapter 1 (max 10K chars)
+plot-02.md      — Chapter 2
+...
+\`\`\`
+
+## structure.md Format
+
+### Required Sections
+
+1. **Core Concept** — One paragraph describing the premise
+2. **Main Characters** — For each character:
+   - Age, Personality, Flaw, Arc
+3. **Story Arc** — Beginning, Middle, End
+4. **Chapter Plan** — Numbered list of planned chapters with one-line descriptions
+5. **Progress Log** — Track what has been written
+
+## genesis.md Format
+
+The genesis is the story's hook — the first thing readers see on-chain.
+
+- ~1000 characters (hard limit for on-chain genesis)
+- Create immediate intrigue or emotional hook
+- Introduce the core premise without spoilers
+- End with a question or tension that pulls readers forward
+
+## plot-NN.md Format
+
+Each chapter is a self-contained prose section:
+
+- Maximum 10,000 characters per file
+- Number sequentially: plot-01.md, plot-02.md, etc.
+- Each chapter should advance the story meaningfully
+- Illustrations: upload via API, embed as \`![description](url)\` in markdown
+
+## Publishing Rules
+
+- Content is **immutable after publish** — verify everything in Preview first
+- Genesis publishes via \`createStoryline\` (one-time per story)
+- Plots publish via \`chainPlot\` (one per chapter)
+- Always check character count before publishing (500–10,000 chars)
+
+## Security — never print secrets into the terminal
+
+- Do NOT print, \`echo\`, \`cat\`, or log auth material in this terminal: no
+  \`Authorization: Bearer\` headers or session tokens, no \`OWS_PASSPHRASE\`, and no
+  login passphrase or any login command that contains it.
+- The app stores the passphrase in \`~/.plotlink-ows/.env\` and authenticates for
+  you — you never need to read or echo it. Use the documented API; keep secrets
+  out of command output.
+`;
+}
+
+/**
+ * Provider-branched clean-image workflow section for cartoon instructions.
+ *
+ * The clean-image-first rules (no dialogue/SFX/bubbles/watermark/signature baked
+ * into art) are shared; only the "who creates the file" contract differs:
+ *
+ * - Codex: creating the real `assets/plot-NN/cut-XX-clean.webp` file is the
+ *   PRIMARY instruction, but it is gated behind a capability/checkpoint guardrail
+ *   (#307) so the session never sits in an indefinite `Working` state: Codex
+ *   makes one bounded attempt, and if image generation is unavailable it reports
+ *   the blocker and falls back to the manual prompt + import path instead of
+ *   hanging. Critically, Codex is never told it cannot create image files (#274)
+ *   — only to verify-and-report rather than stall.
+ * - Claude / legacy (absent provider): Claude does not generate image files in the
+ *   terminal, so the manual prompt + import handoff stays primary (unchanged
+ *   behavior).
+ */
+function cleanImageWorkflowSection(provider: AgentProvider): string {
+  if (provider === "codex") {
+    return `### Write the planning files FIRST — never leave a story shell (#362)
+
+Before you generate (or attempt to generate) ANY image, write the episode's text
+artifacts to the story folder so the story is never left as just \`.story.json\` +
+\`CLAUDE.md\` if image generation stalls or is unavailable:
+
+1. \`structure.md\` (outline, Character Bible, Visual Style Guide)
+2. \`genesis.md\` (the reader-facing prologue/opening)
+3. \`plot-NN.cuts.json\` (the shot-by-shot cut plan, with its real episode \`title\`)
+
+Image generation is the LAST step, not the first. A pilot once spent >10 minutes
+attempting image generation and left the folder with no \`structure.md\`,
+\`genesis.md\`, or \`plot-NN.cuts.json\` at all — that is the failure this rule
+prevents. Save the planning files, confirm they exist in the story folder, and
+only then move on to images. (\`plot-NN.md\` is the exception — OWS generates it
+from cuts.json after final images upload; never hand-write it.)
+
+### Before generating images: confirm capability, checkpoint, and never hang (#307)
+
+Image generation in this session is NOT guaranteed to be available. Before you
+rely on it, follow this guardrail so the terminal never sits in an indefinite
+\`Working\` state with no files and no blocker report:
+
+1. **Checkpoint first, then make ONE bounded attempt.** Before generating, post a
+   one-line status naming the file you are about to create (e.g. "generating
+   cut-01 clean image"). Make exactly ONE attempt per file — never retry image
+   generation in a loop or wait indefinitely for it to finish.
+2. **Confirm the capability on that attempt.** If there is no working in-session
+   image-generation capability — the attempt errors, returns no usable image
+   bytes, or you cannot confirm it quickly — treat image generation as
+   UNAVAILABLE for this session. (Per Asset Tooling, never shell out to
+   \`magick\`/\`sharp\`/Playwright to fake it.)
+3. **Fail visibly, never silently.** The moment image generation is
+   unavailable/blocked, report it in one clear line — "Image generation is
+   unavailable in this Codex session; switching to the prompt-and-import
+   handoff." — then use the Fallback below and stop cleanly. An unreported hang
+   is a bug; a clear blocker report is the correct, expected outcome.
+4. **Report progress per file.** After each saved image or each blocker, post a
+   one-line checkpoint ("cut 2/6 saved" / "cover saved" / "blocked: <reason>") so
+   the writer always sees progress, never a bare spinner.
+
+This guardrail applies to BOTH the cover and every clean cut image. Creating the
+files is still your primary job when generation works (below); the rule is only
+that you verify-and-report instead of stalling.
+
+### Create the clean image file directly — your primary job
+
+When image generation is available (confirm it per the guardrail above), for each
+cut you CREATE THE REAL CLEAN-IMAGE FILE — you do not just return a prompt or
+description. How that image reaches the cut depends on the format your image tool
+produces — there are TWO acceptable outcomes, and a generated PNG is one of them:
+
+1. Generate the clean image for the requested cut from its shot type + description
+   + characters (the OWS UI's per-cut "Copy Codex task" / "Copy prompt" gives you
+   the exact visual prompt). Built-in image generation usually writes a **PNG** into
+   a generation cache such as \`~/.codex/generated_images/…\`, NOT your story folder —
+   that is an EXPECTED, acceptable result, not a failure. Do NOT try to convert it
+   yourself (the Asset Tooling ban forbids \`magick\`/\`sharp\`).
+2. **Get the image onto the cut — pick the path that matches the file you have:**
+   - **Already WebP or JPEG, under 1MB:** finalize it into the OWS asset path. Copy
+     or move the file to \`assets/plot-NN/cut-XX-clean.webp\` — use the episode's
+     \`plot-NN\` folder and the cut's zero-padded id (\`cut-01\`, \`cut-02\`, …). A plain
+     file copy/move (\`cp\`/\`mv\`) is fine — the Asset Tooling ban is only on using
+     \`magick\`/\`sharp\`/Playwright to resize/convert/composite/measure. Then run the
+     OWS "Sync clean images" action so OWS records \`cleanImagePath\`.
+   - **A PNG (the common case), or any file OWS will not take directly:** do NOT
+     convert it and do NOT rename a \`.png\` to \`.webp\` — a PNG saved under a \`.webp\`
+     name is not a valid clean asset, and OWS rejects it on its content check. Leave
+     the file where it is and report it on an \`IMPORT NEEDED\` line (below); the
+     writer imports it into that exact cut with the OWS per-cut **"Import from
+     Codex"** button, which converts the generated PNG to a compliant WebP
+     automatically and records \`cleanImagePath\`. Importing a generated PNG this way
+     is a normal, supported finish — not a fallback, and not something you should
+     keep retrying to avoid.
+3. The image must contain NO text, captions, speech bubbles, SFX lettering,
+   readable signage, watermark, or signature.
+4. **Validate at the OWS path before reporting success.** A cut counts as SAVED only
+   when \`assets/plot-NN/cut-XX-clean.webp\` really exists — e.g.
+   \`find assets/plot-NN -name 'cut-XX-clean.*'\`, with \`file\` reporting WebP or JPEG
+   under 1MB (existence/type/size checks like \`find\`/\`file\` are allowed — they don't
+   manipulate the image). A cut whose image is still a PNG in
+   \`~/.codex/generated_images/…\` is NOT "saved" — list it as \`IMPORT NEEDED\` so the
+   writer imports it via "Import from Codex", and never hand-write a \`cleanImagePath\`
+   for a file that is not really at the OWS path.
+
+**Only exception:** Include text in an image when it is part of the physical scene
+(a sign on a building, text on a screen, a letter being read) AND the writer has
+explicitly requested it.
+
+### Fallback: hand the prompt to the writer (only if image generation is unavailable)
+
+If image generation is not available in this session, do not block — fall back to
+the manual handoff for each cut:
+1. PREPARE THE EXACT CLEAN-IMAGE PROMPT (shot type + description + characters +
+   the no-text constraint). This is the same prompt the OWS UI exposes per cut.
+2. Tell the writer to generate it externally (any provider/tool) and then
+   upload/import the resulting WebP/JPEG into OWS using the per-cut "Copy prompt" +
+   "Upload clean image" controls.
+3. **Do NOT claim that \`assets/plot-NN/cut-XX-clean.webp\` was created unless the
+   file actually exists.** Never report an image as generated when you only
+   produced a prompt.
+
+### Cover fallback (only if cover generation is unavailable)
+
+The cover follows the same guardrail. If you cannot generate \`assets/cover.webp\`
+in this session, do NOT hang on the cover: say so in one line and tell the writer
+to import a cover via the OWS "Import generated image" control on the genesis
+publish panel (it accepts a PNG and converts it). The same one-attempt-then-report
+rule applies to a cover-only request.
+
+### Finishing the task: post a completion line and STOP (#311)
+
+You are DONE once every requested cut has been handled — each one either has its
+verified clean-image file saved, OR a clear blocker reported and the
+prompt-and-import fallback handed off — and the cover is saved or its fallback
+reported. Verifying that each file exists at the right path, format, and size is
+ALL the checking required.
+
+Do NOT start an open-ended "let me visually re-inspect the images" loop: you
+cannot meaningfully re-judge generated art from a terminal, and looping there is
+exactly what leaves the OWS session stuck in a long-running \`Working\` state after
+the files already exist.
+
+Post ONE final completion line, then STOP (return to the idle prompt — do not keep
+working or wait for more input):
+
+  CARTOON ASSETS COMPLETE — N/N clean cut images saved, cover <saved|skipped>. Ready for lettering in OWS.
+
+If some assets are blocked, use instead:
+
+  CARTOON ASSETS PARTIAL — X/N clean cut images saved, Y blocked: <reasons>. Ready for lettering on the saved cuts in OWS.
+
+**Hand off generated PNGs for one-click import (#403).** Any cut whose image is a
+PNG left in \`~/.codex/generated_images/…\` (the normal output of built-in
+generation) must be named for the writer so they can import it — never silently
+leave it in the cache, where a writer cannot find it. For each such file, list its
+real source path and the cut/cover it belongs to, e.g.:
+
+  IMPORT NEEDED — cut 3: ~/.codex/generated_images/<file>.png → import into cut 3 with the OWS per-cut "Import from Codex" button (it converts the PNG automatically).
+  IMPORT NEEDED — cover: ~/.codex/generated_images/<file>.png → import via the genesis panel's "Import generated image" control.
+
+A generated PNG handed off this way is a complete, expected result — list every one
+so none is stranded, and do NOT re-attempt generation just to avoid the import.
+
+### Post-run checklist — files live in the STORY FOLDER, not the cache (#362)
+
+Before you post the completion line, confirm in the story folder itself (not in
+\`~/.codex/generated_images/\`):
+
+- \`structure.md\`, \`genesis.md\`, and every \`plot-NN.cuts.json\` exist.
+- Each cut you reported as saved has a real \`assets/plot-NN/cut-XX-clean.webp\`
+  (WebP/JPEG, < 1MB) at that path — verify with \`find\`/\`file\`, not from memory.
+- The cover, if generated, is at \`assets/cover.webp\`.
+- Any image you could NOT finalize is named in an \`IMPORT NEEDED\` line above.
+
+If a file is only in the generation cache, it does not count as saved — either
+finalize it into the asset path or report it as \`IMPORT NEEDED\`.
+
+After that line, the lettering/export/publish steps are the writer's job in OWS —
+hand off and stop.`;
+  }
+
+  return `### You cannot create image files yourself — hand the prompt to the writer
+
+You (Claude) do **not** generate image files in this terminal. You produce the
+exact clean-image PROMPT for each cut; the writer (or a configured image tool, if
+any) generates the actual image externally and imports it back into OWS.
+
+If no image-generation tool is available in the terminal, for each cut:
+1. PREPARE THE EXACT CLEAN-IMAGE PROMPT (shot type + description + characters +
+   the no-text constraint). This is the same prompt the OWS UI exposes per cut.
+2. Tell the writer to generate it externally (any provider/tool they prefer) and
+   then upload/import the resulting WebP/JPEG into OWS using the per-cut
+   "Copy prompt" + "Upload clean image" controls.
+3. **Do NOT claim that \`assets/plot-NN/cut-XX-clean.webp\` was created unless the
+   file actually exists.** Never report an image as generated when you only
+   produced a prompt.
+4. After a clean image file exists, update/verify the cut's \`cleanImagePath\`
+   through the OWS import flow or the cuts API — do not invent the path.
+
+If a configured image tool exists, it may generate the clean image directly;
+otherwise the manual prompt + import path above is the safe baseline.
+
+Saved clean images live at: \`assets/plot-NN/cut-XX-clean.webp\` (OWS records the
+path; you do not hand-write it unless the file is really there).
+
+**Only exception:** Include text in images when it is part of the physical scene
+(a sign on a building, text on a screen, a letter being read) AND the writer
+has explicitly requested it.`;
+}
+
+/** Provider-branched step 2 of the Episode Workflow checklist. */
+function episodeWorkflowImageStep(provider: AgentProvider): string {
+  if (provider === "codex") {
+    return `2. **Generate** — Write the planning files first. Create the real clean-image file for each cut.
+   If it is WebP/JPEG under 1MB, finalize it into \`assets/plot-NN/cut-XX-clean.webp\`;
+   if it is a PNG (the usual built-in output), leave it in the cache and hand it off
+   with an \`IMPORT NEEDED\` line for the writer's per-cut "Import from Codex" button —
+   both are acceptable finishes. Checkpoint per file and make one bounded attempt; if
+   image generation is unavailable, report the blocker and fall back to preparing the
+   prompt for the writer to import — never sit in an indefinite \`Working\` state.`;
+  }
+  return `2. **Prompt & import** — Prepare the clean-image prompt for each cut; the writer
+   generates it externally (or a configured image tool, if any) and uploads/
+   imports the clean image via OWS. You do not create the image file yourself.`;
+}
+
+function cartoonInstructions(provider: AgentProvider): string {
+  return `# Writing Instructions — Cartoon
+
+> Auto-generated by PlotLink OWS. Do not edit manually.
+> For API endpoints and publish details, see ~/.plotlink-ows/CLAUDE.md.
+
+## Story File Structure
+
+\`\`\`
+.story.json              — { "contentType": "cartoon" }
+structure.md             — Story bible: style guide, character bible, episode format (outline, not publishable)
+genesis.md               — Reader-facing prologue / Episode 1 opening (prose, real # title)
+genesis.cuts.json        — Cut plan for Genesis-as-Episode-1 ({ "plotFile": "genesis", cuts: [...] })
+plot-NN.cuts.json        — Cut plan for episode NN
+plot-NN.md               — Episode publish markdown (image sequence, generated from final uploaded images)
+assets/
+  plot-NN/               — (and assets/genesis/ for Genesis cuts)
+    cut-01-clean.webp    — Clean image (no text or bubbles)
+    cut-01-final.webp    — Final lettered version
+    ...
+\`\`\`
+
+### Scaffold states (keep these explicit)
+
+A new cartoon scaffold has four distinguishable states — don't let a placeholder
+look publish-ready:
+
+- **Story bible / outline** — \`structure.md\`. Never publishable; it's the plan.
+- **Episode 1 planned** — \`genesis.md\` (prose opening) + \`genesis.cuts.json\`
+  with real cuts. Use \`"plotFile": "genesis"\` — OWS supports Genesis as
+  Episode 1, not only \`plot-NN\`.
+- **Future episode placeholder** — a \`plot-NN.cuts.json\` with \`"cuts": []\` (and
+  a stub \`plot-NN.md\`) is a **planned / not-started** episode. Leave \`cuts\`
+  empty until you actually plan that episode; OWS shows it as "not started", not
+  "ready to publish". Do NOT hand-write publish markdown for it.
+- **Publish markdown** — \`plot-NN.md\` is generated by OWS from the final
+  uploaded cut images (the "Prepare episode for publish" step), never authored by
+  hand.
+
+## structure.md Format (Cartoon)
+
+### Required Sections
+
+1. **Visual Style Guide**
+   - Art style (manga, Franco-Belgian, webcomic, American comic, etc.)
+   - Color palette (full color, limited palette, monochrome + spot color)
+   - Line weight and inking style
+   - Panel/cut layout preferences (grid, dynamic, full-bleed)
+   - **Style Lock (REQUIRED — prevents photoreal drift).** Write one short,
+     reusable block that locks the rendering style and you repeat on EVERY image
+     generation. It MUST carry both positive descriptors and hard negatives,
+     because image generation drifts into polished digital painting / photoreal
+     concept art unless the prompt fights it. Pattern (adapt the specifics to this
+     story's reference, e.g. a semi-realistic Korean webtoon):
+     - **Positive:** illustrated comic/webtoon panel art; clean black contour/ink
+       lines; flat or cel shading; simplified-but-realistic (semi-realistic)
+       anatomy and faces; backgrounds drawn as illustrated panels, not photos.
+     - **Hard negatives:** NOT photorealistic, NOT a photograph, NOT a glossy or
+       painterly digital painting, NOT concept art, NOT a 3D/CGI render, NOT
+       airbrushed, no photoreal textures.
+     "Semi-realistic webtoon" on its own is too weak — keep the explicit negatives.
+     OWS already prepends a baseline style lock to every per-cut "Copy Codex task" /
+     "Copy prompt"; your Style Lock here adds the story-specific reference on top and
+     must be honored on the cover too.
+
+2. **Character Bible**
+   For each character, describe their VISUAL identity:
+   - Physical features: hair color/style, eye color, build, height
+   - Signature outfit and accessories
+   - Distinguishing visual features (scars, glasses, tattoos)
+   - Expression notes (resting expression, characteristic gestures)
+
+3. **Episode Format**
+   - Target cuts per episode (typical: 4–12)
+   - Pacing rhythm: how to alternate wide/medium/close-up shots
+   - Aspect ratio preference for cuts
+
+4. **Bubble and Lettering Conventions**
+   - Speech bubble style (round, angular, cloud-like)
+   - Thought bubble style
+   - Narration/caption box style
+   - Sound effect (SFX) conventions
+   - Font or lettering style preferences
+
+5. **Cut Planning Rules**
+   - Shot progression guidelines (e.g., establish → act → react)
+   - When to use wide vs. close-up shots
+   - Transition conventions between scenes
+
+6. **Genesis Opening Plan (Reader Onboarding)**
+   - How Genesis opens the story for readers: the lead's situation and their
+     emotional/comedic problem, the tone, and what's at stake.
+   - The bridge from Genesis into episode 1 — what plot-01 picks up, so the
+     prologue and the first episode connect without restarting or repeating.
+   - Keep it text-only for MVP; note the intended title.
+
+## genesis.md Format — Reader-facing Prologue / Story Opening
+
+On PlotLink the story page **opens at Genesis**, so for a cartoon write \`genesis.md\`
+as the actual **prologue / story opening readers see first** — NOT a back-cover
+synopsis, and NOT a cold jump into scene 1. It is text-only for this MVP (no
+image cuts) and **must start with a real \`# Title\` heading** (the published
+chapter title).
+
+Write it as polished reader-facing prose (~600–1000 characters) across **3–6
+short paragraphs** that build — do NOT compress the opening into a single block
+or a one-line premise. Let the prologue breathe across these beats:
+
+- **Opens on the main character's situation** and their emotional or comedic
+  problem — put us in a moment, not a pitch.
+- **What the lead wants** (their desire/goal) and **what's at stake** — give the
+  reader someone to root for before the first episode.
+- **Establishes tone and premise** — the comedic/romantic hook that makes this
+  story this story.
+- **Builds toward the first visual episode** and ends on a beat that hands off
+  into Episode 01 — a clear bridge, so plot-01 feels like the story continuing,
+  not starting over.
+- **Avoids lore dumps** and worldbuilding exposition — reveal through the
+  character's immediate situation.
+- For comedic romance / webtoon pacing: lead with the funny/awkward hook and the
+  relationship tension; keep it warm and propulsive.
+
+A single dense paragraph or a bare logline is NOT enough — readers meet Genesis
+first, so it must onboard them with real buildup, not drop them cold into a scene.
+
+Genesis vs plot-01: **Genesis opens and onboards the reader** (prose prologue);
+**plot-01 is the first cut-based visual episode** that must **open on a titled
+beat continuing directly from where Genesis leaves off** — not a cold jump and
+not a restart. Do not start plot-01 without the setup Genesis provides, and do
+not duplicate the prologue inside plot-01.
+
+## Cut Planning — plot-NN.cuts.json
+
+Before generating images for an episode, create the cut plan first. The cuts.json
+is the single source of truth for the episode's visual sequence.
+
+**CRITICAL: Use this EXACT schema. Do NOT invent alternate or nested planning
+structures.** OWS reads this file with a strict validator — any other shape is
+rejected.
+
+Valid \`plot-01.cuts.json\`:
+
+\`\`\`json
+{
+  "version": 1,
+  "plotFile": "plot-01",
+  "title": "Episode 1 — First Rain",
+  "cuts": [
+    {
+      "id": 1,
+      "shotType": "wide",
+      "description": "Establishing shot of the rain-soaked city at dusk",
+      "characters": ["Mira"],
+      "dialogue": [
+        { "speaker": "Mira", "text": "It always rains here." }
+      ],
+      "narration": "The city never slept, and neither did she.",
+      "sfx": "RAIN",
+      "cleanImagePath": null,
+      "finalImagePath": null,
+      "exportedAt": null,
+      "uploadedCid": null,
+      "uploadedUrl": null,
+      "overlays": []
+    }
+  ]
+}
+\`\`\`
+
+**Always set a top-level \`title\`** — a real, **reader-facing, specific** episode
+title (e.g. "Episode 1 — First Rain", or just "First Rain"). The published
+cartoon markdown is image-only with no heading, so this \`title\` becomes the
+**public chapter title readers see on PlotLink**. It must NOT be a default or
+placeholder label: never the raw filename \`plot-01\`, and never a bare generic
+"Episode NN"/"Chapter NN". OWS **blocks** publish on those (#347/#358/#365/#368)
+and, after publish, **verifies the indexed public title** is reader-facing
+(#379). The same rule applies to the story itself — **Genesis must carry a real
+\`# Title\`, never the default \`Genesis\` label**. EVERY episode needs a public
+title specific to what happens in it, not a numbered placeholder.
+
+### Text / interstitial panels (#352)
+
+A cut may be a **text panel** instead of an image cut — a narration card, title
+card, time/scene transition ("Three weeks later"), or a beat of pure prose for
+pacing/buildup. Set \`"kind": "text"\` on the cut (image cuts omit \`kind\` or use
+\`"image"\`). A text panel needs **no clean image**: it renders text on a styled
+background and still exports + uploads a final image like any cut.
+
+\`\`\`json
+{ "id": 4, "kind": "text", "shotType": "wide", "description": "Time skip",
+  "background": "#101820", "aspectRatio": "4:5",
+  "characters": [], "dialogue": [], "narration": "Three weeks later.", "sfx": "",
+  "cleanImagePath": null, "finalImagePath": null, "exportedAt": null,
+  "uploadedCid": null, "uploadedUrl": null, "overlays": [] }
+\`\`\`
+
+Use text panels **between image cuts** to control rhythm — an opening title, a
+scene/time transition, an interior-monologue beat, or buildup before a reveal.
+Optional \`background\` (CSS color) and \`aspectRatio\` ("W:H") style the card. In
+OWS the writer can also add one with the **"Add text panel"** button, then open
+the lettering editor to place the text. Don't overuse them; they punctuate the
+visual story, they don't replace it.
+
+### Required field naming (do NOT use the wrong forms)
+
+| Use this | NOT this |
+|----------|----------|
+| \`version: 1\` (top level) | \`$schema\`, \`story\`, \`workflow\`, \`promptDefaults\` |
+| numeric \`id\` (1, 2, 3) | string ids like \`"c01"\` |
+| \`shotType\` | \`shot\` |
+| \`description\` | nested \`image.prompt\` |
+| \`dialogue[].text\` | \`dialogue[].line\` |
+| \`narration\` (string) | nested \`text.narration\` |
+| \`sfx\` (single string) | \`sfx\` as an array |
+| \`cleanImagePath\` / \`finalImagePath\` (top-level on the cut) | nested \`image.clean\` / \`image.final\` |
+
+- \`shotType\` must be one of: \`wide\`, \`medium\`, \`close-up\`, \`extreme-close-up\`.
+- All image/export/upload path fields start as \`null\`; OWS fills them in.
+- \`overlays\` starts as an empty array \`[]\`; the lettering editor populates it.
+  **Leave \`overlays\` empty (\`[]\`)** — the writer places bubbles/captions in the
+  OWS lettering editor. If you ever do emit overlays, each MUST use the real OWS
+  overlay schema below — NEVER a semantic \`position\` string like \`"upper-left"\`,
+  which has no geometry, does not render, and would export a blank, unlettered
+  image.
+- **Overlay schema (only if you emit overlays):** each overlay is an object with
+  \`id\` (string), \`type\` (\`"speech"\` | \`"narration"\` | \`"sfx"\`), numeric \`x\`, \`y\`,
+  \`width\`, \`height\` (fractions of the image, 0–1, where \`x\`/\`y\` are the top-left
+  corner), \`text\` (string), optional \`speaker\` (speech only), and optional
+  \`tailAnchor\` (\`{ "x": number, "y": number }\`, speech only). Example:
+  \`{ "id": "ov-1", "type": "speech", "x": 0.08, "y": 0.06, "width": 0.4, "height": 0.16, "text": "...", "speaker": "Hana", "tailAnchor": { "x": 0.5, "y": 1.2 } }\`.
+  There is NO \`position\` field.
+- **Every publishable cut must become a final uploaded image.** Even
+  narration-only or background-only cuts must get a clean image, be lettered/
+  exported, and uploaded before the episode can publish. \`cleanImagePath\` may
+  be \`null\` during early planning, but a cut with no uploaded image will block
+  publish readiness.
+
+## Asset Tooling — use OWS flows, do NOT shell out to image tools
+
+OWS owns the cartoon asset pipeline. Local image tools are NOT part of the
+contract and may be absent — do **NOT** call ImageMagick (\`magick\`/\`convert\`/
+\`identify\`), \`sharp\`, Playwright / headless browsers, or any ad-hoc shell tool to
+resize, convert, composite, letter, or measure images. If you find yourself
+reaching for a CLI image tool, STOP — there is a supported OWS action for it, and
+guessing at unavailable tooling is exactly what stalls a cartoon episode.
+
+**Deterministic handoff — who does what:**
+
+| Step | Who | How (no shell image tools) |
+|------|-----|----------------------------|
+| Generate clean cut images | You (Codex) | Generate the image. If it is WebP/JPEG < 1MB, finalize it into \`assets/plot-NN/cut-XX-clean.webp\` with a plain \`cp\`/\`mv\`. If it is a PNG (the usual built-in output), do NOT convert or rename it — hand it off with an \`IMPORT NEEDED\` line for the writer's "Import from Codex" button, which converts it automatically. Either is a valid finish; do NOT post-process with magick/sharp. |
+| Generate the cover | You (Codex) | Save \`assets/cover.webp\` (~600x900, WebP, < 1MB). OWS auto-detects it for genesis publish — no manual selection needed. |
+| Discover / record clean images | OWS | Run the "Sync clean images" action (or let OWS auto-detect); OWS records \`cleanImagePath\`. Never hand-write paths or stat files yourself. |
+| Letter & export final images | The writer, in the OWS lettering editor | Speech bubbles, captions, and SFX are placed in the OWS editor and exported to \`assets/plot-NN/cut-XX-final.webp\`. You do NOT composite or letter text — not with magick, not with sharp, not at all. |
+| Upload finals + build markdown | OWS | The writer runs "Upload & Prepare for Publish"; OWS uploads each final image and emits the publish markdown. You never hand-write \`plot-NN.md\`. |
+
+**No agent-side image tools are required** — OWS provides image generation (your
+session), clean-image sync, the lettering/export editor, and upload/markdown
+generation. If a capability you genuinely need is missing (e.g. image generation
+itself is unavailable in this session), do NOT improvise with shell tools: fall
+back to the prompt-and-import handoff below and tell the writer, so the missing
+capability surfaces immediately instead of after a dead-end path.
+
+## CRITICAL: Clean-Image-First Workflow
+
+**Do NOT bake dialogue, speech bubbles, sound effects, or any text into generated images.**
+
+Clean images must contain:
+- No speech bubbles
+- No text overlays
+- No sound effect text
+- No narration captions
+- No lettering of any kind
+
+**Lock the style on every generation — do not drift to photoreal.** Reuse the
+**Style Lock** from structure.md's Visual Style Guide in EVERY image prompt (cuts
+and cover) so the look stays consistent and illustrated. The requested style is an
+illustrated comic/webtoon panel — clean black contour lines, flat/cel shading,
+simplified-but-realistic anatomy — and explicitly **NOT** photorealistic, **NOT** a
+painterly digital painting / concept art, and **NOT** a 3D render. If a generated
+image reads as a photo or polished concept art, it is off-style: regenerate it as
+illustrated panel art rather than accepting the drift. (The per-cut "Copy Codex
+task" / "Copy prompt" OWS exposes already carries this baseline style lock.)
+
+${cleanImageWorkflowSection(provider)}
+
+## Character Consistency
+
+- Reference the character bible from structure.md for EVERY image generation
+- Maintain consistent visual traits across all cuts and all episodes
+- Same hair, same eye color, same outfit unless the story dictates a change
+- Note any intentional appearance changes in the cuts.json
+
+## Lettering Handoff
+
+After clean images are generated and approved by the writer:
+
+1. The writer uses the OWS lettering editor to add speech bubbles and text
+2. Lettered versions are saved as: \`assets/plot-NN/cut-XX-final.webp\` (the OWS
+   editor's export writes this file — you do not create or composite it)
+3. Do NOT attempt to add bubbles or text to images — only the writer controls
+   lettering, via the OWS editor. Never composite text with \`magick\`, \`sharp\`,
+   Playwright, or any other tool; lettering/export is not an agent shell task.
+4. The publish markdown references final lettered images, not clean images
+
+## Publish Markdown — plot-NN.md
+
+**Do NOT hand-write plot-NN.md with image links.** OWS generates the publish
+markdown from cuts.json after final images are uploaded. Hand-authored markdown
+with local asset paths (\`assets/...\`) or placeholder URLs ("final image
+pending") will be rejected by publish readiness checks.
+
+Correct flow:
+
+1. Upload final (lettered) images via OWS — this records the IPFS URL per cut in
+   cuts.json (\`uploadedUrl\`).
+2. Use OWS "Prepare episode for publish" / "Upload & Prepare for Publish" to produce
+   plot-NN.md. OWS emits marker-delimited blocks:
+   \`\`\`
+   <!-- ows:cartoon-cut cut-001 start -->
+   ![Cut 1 — Scene description](https://ipfs-gateway/...)
+   <!-- ows:cartoon-cut cut-001 end -->
+   \`\`\`
+3. Cuts that are not yet uploaded produce a safe \`<!-- ... awaiting upload -->\`
+   comment, never a fake image URL. Publish is blocked until all cuts upload.
+4. Each image is WebP or JPEG, under 1MB. Total markdown under 10K characters.
+5. Keep human-readable planning notes in cuts.json or structure.md — never as
+   fake publish image links.
+
+## Publishing Rules
+
+- Content is **immutable after publish** — verify all images in Preview first
+- Genesis publishes via \`createStoryline\` (one-time, text-only synopsis)
+- Episodes publish via \`chainPlot\` (per episode, image-sequence markdown)
+- Once published, images cannot be replaced or edited
+
+## Security — never print secrets into the terminal
+
+- Do NOT print, \`echo\`, \`cat\`, or log auth material in this terminal: no
+  \`Authorization: Bearer\` headers or session tokens, no \`OWS_PASSPHRASE\`, and no
+  login passphrase or any login command that contains it.
+- The app stores the passphrase in \`~/.plotlink-ows/.env\` and authenticates for
+  you — you never need to read or echo it. Use the documented API; keep secrets
+  out of command output.
+
+## Episode Workflow
+
+1. **Plan** — Create plot-NN.cuts.json with shot-by-shot breakdown
+${episodeWorkflowImageStep(provider)}
+3. **Review** — Writer reviews clean images, requests adjustments
+4. **Letter** — Writer adds speech bubbles and text via lettering editor
+5. **Upload** — Upload final lettered images to get IPFS URLs (recorded in cuts.json)
+6. **Generate** — Use OWS to generate plot-NN.md from cuts.json (do not hand-write it)
+7. **Preview** — Verify all images render correctly
+8. **Publish** — Chain the episode (immutable after this step)
+
+## Final response format — end EVERY completed task with this (#419)
+
+A validation summary alone is not enough: a non-technical writer needs to know
+exactly what to do next and what to paste back to you. So after ANY major task
+(story setup, episode planning, clean-image generation, lettering handoff,
+export, upload, publish), end your reply with this exact five-part section, in
+plain language (no jargon, no internal file paths in the pasteable prompt):
+
+\`\`\`
+Done
+- <3-5 short bullets of what changed>
+
+Current stage
+- <one line, e.g. "Episode 1 planned; clean images not generated yet">
+
+Next recommended action
+- <one clear action in plain language>
+
+Prompt you can paste next
+- <a single copy-paste prompt the writer can hand back to you>
+
+Do not do yet
+- <short safeguards when relevant; omit the bullet if nothing applies>
+\`\`\`
+
+Pick the "Prompt you can paste next" to match the stage you just finished:
+
+- **After story setup** → \`Plan the cuts for Episode 1 / Genesis. Don't generate images, letter, upload, or publish yet.\`
+- **After episode planning** → \`Generate clean images for Episode 1 / Genesis from genesis.cuts.json. Do not letter, upload, or publish yet.\`
+- **After clean images** → \`The clean images for Episode 1 are ready — review them, then I'll letter them in the OWS editor.\` (lettering/export/upload happen in the OWS UI, not via the agent)
+- **After lettering/export/upload** → \`Episode 1's final images are uploaded — prepare the publish markdown and show me the Preview before publishing.\`
+- **After publish** → \`Verify Episode 1 is live on plotlink.xyz, then let's plan Episode 2.\`
+
+Keep it concise — this section replaces a long technical status dump, it does not
+add to one. Write the whole section in the writer's language. This format is
+required for cartoon stories regardless of which assistant (Claude or Codex) you
+are; it never applies to fiction stories.
+`;
+}
+
+export function generateStoryInstructions(
+  contentType: "fiction" | "cartoon",
+  // Cartoon instructions branch by provider so a Codex cartoon session is told to
+  // create the real clean-image file, while Claude/legacy sessions get the manual
+  // prompt-and-import handoff. Fiction ignores provider (always Claude). Absent ⇒
+  // "claude" (matches the fiction-safe absent⇒Claude default; see #268).
+  provider: AgentProvider = "claude",
+): string {
+  if (contentType === "cartoon") return cartoonInstructions(provider);
+  return fictionInstructions();
+}
+
+const MARKER_PREFIX = "<!-- plotlink-ows:story-instructions:";
+
+// Cartoon markers encode the provider so a story repaired Claude⇒Codex (or vice
+// versa) regenerates its CLAUDE.md on the next spawn instead of keeping stale,
+// provider-mismatched wording. Fiction has no provider variant — its marker is
+// unchanged for rollback safety.
+function marker(contentType: "fiction" | "cartoon", provider: AgentProvider): string {
+  const suffix = contentType === "cartoon" ? `cartoon:${provider}` : "fiction";
+  return `${MARKER_PREFIX}${suffix} -->`;
+}
+
+export function writeStoryInstructions(
+  storyDir: string,
+  contentType: "fiction" | "cartoon",
+  provider: AgentProvider = "claude",
+): void {
+  const claudeMdPath = path.join(storyDir, "CLAUDE.md");
+  const expectedMarker = marker(contentType, provider);
+
+  if (fs.existsSync(claudeMdPath)) {
+    try {
+      const firstLine = fs.readFileSync(claudeMdPath, "utf-8").split("\n")[0];
+      if (firstLine === expectedMarker) return;
+      if (!firstLine.startsWith(MARKER_PREFIX)) return;
+    } catch { /* regenerate on error */ }
+  }
+
+  const content = expectedMarker + "\n" + generateStoryInstructions(contentType, provider);
+  fs.writeFileSync(claudeMdPath, content, "utf-8");
+}