# Phase 1 — Authored Source of Truth (the layer→skill index)

> **Canonical workflow = [`../SKILL.md`](../SKILL.md)** — the comic-author orchestrator (the ordered 9-step
> pipeline intent→style→outline→storyboard→assets→blueprints→prompts→`comic.json`, each step a detailed skill +
> its `comic-cross-layer-gate` gate). This document is the **per-layer detail + the executed worked-example
> artifacts** behind that pipeline; the orchestrator is the source of truth for ORDER, GATES, and BARRIERS.

This is the **left third of Figure 1** — *Asset Library → Outline → Storyboard → `comic.json`* — turned into a
followable procedure so it isn't left for the user to reinvent. You hand your agent a fuzzy idea; your agent
runs **these layers** to produce `comic.json` + its assets; then
[`run_comic.py`](../../comic-director/scripts/run_comic.py) (the `comic-director` skill, Phase 2/3) bakes +
adversarially verifies it. The reference movie's Phase-1 **executed artifacts** are the `gen/` scripts under
`examples/comic_m3_audit/` (cited per layer). This mirrors the
[ARIS](https://github.com/wanshuiyin/Auto-claude-code-research-in-sleep) main project's intent→outline→
storyboard pipeline; ARIS main is one such authoring agent (optional, not a runtime dependency).

> **Does the user build the asset library?** No — the agent does, by following Layer 3. But the asset library
> IS required input: `comic.json` references content-SVG blueprints + identity refs that must exist before a
> bake. They are *authored*, not free — the framework verifies your numbers/cast, it doesn't invent them.

Each layer ends with a **gate** (cross-model where it's a quality/correctness call — executor ≠ reviewer,
same rule as the panel_gate). Author once, lock, move on.

## Two engine contracts you must author to (fail-closed — the #1 source of "why won't it bake")
1. **Every panel needs a `condition.content_svg`** — a deterministic blueprint SVG. The engine requires one
   for *every* panel (it's the content authority + the bake's layout ref), not only figure panels. A
   scene-only panel still gets a simple **layout** blueprint SVG.
2. **A `baked` panel that carries a figure must declare `condition.expected_literals`** (the exact
   numbers/keys/code tokens, verbatim) — else the run is *refused*. A scene panel with no audited numbers
   should be `text_mode: "html"` (dialogue as an HTML overlay, no baked-literal contract). **Do NOT use
   `content_svg: null`** — the engine rejects it.

---

## Layer 0 · Intent (fuzzy idea → locked premise + cast)
**Out:** the top of a `comic_brief` ([`../schemas/comic_brief.schema.json`](../schemas/comic_brief.schema.json)):
`logline`, `thesis`, `cast[]` **+ one locked identity ref (.png) per character** (BYO; the ARIS duo is only
the example), `worlds[]` (palette tags, e.g. `warm-lab` / `dark-cyber`), and `bake_lang` (the PRIMARY language
baked into images; the alternate is still authored in Layer 2 for the viewer toggle).
**Gate:** completeness — premise, cast, identity refs, page count are all resolved (capture uncertainties
explicitly, don't guess).

## Layer 1 · Outline (premise → beats, one per page)
**Out:** `comic_brief.beats[]` — ordered story beats, each with a page `type` (cover / single / grid /
grid2x2 / feature / finale), the cast/world it uses, and a one-line narration. (Reference = 13 beats / 19 pages.)
**Gate:** coverage (the beats tell the whole thesis) + each beat is feasible with the locked cast.

## Layer 2 · Storyboard (beats → full per-panel spec — including layout)
For each panel author the complete spec — **not just `condition`, also the render/layout fields the viewer
consumes** (this is where agents otherwise stall):
- `condition`: `world` · `scene` · `chibi_action` (per-character staging) · and the **plan** for its
  `content_svg` blueprint + (if it carries a figure) the `expected_literals` it must preserve.
- **render/layout (author these here):** `text_mode` (`baked` = dialogue drawn in; `html` = HTML bubble
  overlay), `bubbles[]` `{speaker, style, text:{zh,en}}`, `caption{zh,en}`, `crop{shape,position,zoom}` (the
  focal point so faces/figures aren't sliced), and `safe_zones[]` (clean regions; every `bubble.anchor` must
  resolve to one).
- **page-level (cover / finale):** the `kicker` / `title` / `tag` / `links` (cover) and `closing` (finale)
  fields the viewer renders — author them on the page, not the panel.
This layer also **surfaces the consolidated asset_requests**: the list of recurring motifs + the per-panel
blueprints Layer 3 must build.
**Gate:** every panel has a text_mode + a blueprint plan; every baked figure-panel has its `expected_literals`
listed; every bubble anchor has a safe_zone.

## Layer 3 · Asset Library + blueprints ("one visual dialect, never two")
Build, as **single-source** deterministic SVGs, everything Layer 2 requested: the recurring motifs (clocks,
stamps, mugs, charts…) **and** every panel's `content_svg` blueprint.
- **Author SVGs by WRITING A PYTHON GENERATOR SCRIPT, not by emitting raw SVG/XML in chat** — LLMs get raw
  SVG coordinates wrong; a script is precise, debuggable, and keeps one source per asset. Mirror the worked
  example: `examples/comic_m3_audit/gen/asset_lib.py` (shared single-source builders) →
  `gen_core_assets.py` (the asset library) → `gen_b0*_blueprints.py` (per-panel `content_svg`).
- Also finalize **`ART_BIBLE.md`** (the world/style rules — `run_comic.py` reads it into every bake prompt)
  and the identity refs from Layer 0.
- **MANDATORY GATE — single-source:** run the collision check
  (`examples/comic_m3_audit/gen/check_asset_collisions.py`, or the same rule) — it FAILS if any asset
  filename is written by >1 generator. This is "one visual dialect, never two" enforced by tool, not intent.
- **Gate:** identity-lock on-model + single-source clean + every referenced `content_svg`/`identity_ref` exists.

## Layer 4 · Compile → `comic.json`
Assemble `pages[]` + `panels{}` per [`../../../schemas/comic.schema.json`](../../../schemas/comic.schema.json)
(fields in [`../../../docs/comic-json.md`](../../../docs/comic-json.md)); copy
`examples/comic_m3_audit/comic.json` as the shape. Author only the **authored** fields; leave `image_path` /
`active_attempt_id` / `wiki_node_id` empty — Phase 2/3 writes them on KEEP.
**Gate:** `comic.json` validates (jsonschema); every page's `panel_ids` resolve; every figure-panel has
`expected_literals`; every panel has a real `content_svg`.

---

## Hand-off to Phase 2/3 (the `comic-director` skill)
```bash
python3 skills/comic-director/scripts/run_comic.py --project examples/<name> --page <P> --panels S01,S02 --dry-run
```
`--dry-run` prints each panel's concrete bake prompt from your authored `comic.json` — real scenes + real
literals, no placeholders, and the fail-closed gate passes = Phase 1 is done right. Then drop `--dry-run` to
bake. Field mapping: [`comic_authoring.md`](comic_authoring.md). Render/verify contract: the
[`comic-director`](../../comic-director/SKILL.md) skill.

# Authoring a movie — fuzzy idea → `comic.json` (you don't hand-write JSON)

You should **not** type `comic.json` by hand. The intended path mirrors the figure side's
`brief → Step-0 → blueprint`: you give your agent a vague idea, your agent authors the structured IR, and
this repo's tools render + adversarially verify it. `comic.json` is the **contract boundary** — the agent
authors it; the engine (`run_comic.py`) fills the generation results back in.

```
fuzzy idea (one line / a script / mixed)
   │  Step-0 — an LLM authoring step (YOUR agent: Claude, or via the ARIS main repo)
   ▼
comic_brief.json   (schemas/comic_brief.schema.json — the canonical hand-off:
                    beats[] · cast + identity refs · per-panel headline numbers/claims ·
                    world (warm-lab / dark-cyber) · text_mode intent)
   │  Step-0 compiles the brief → a schema-valid comic.json
   │    • pages[] + panel_ids                         (page layout / reading order)
   │    • per-panel condition{} — WHAT TO GENERATE:
   │        content_svg       (author one deterministic SVG blueprint per figure-bearing panel)
   │        expected_literals (REQUIRED when content_svg is set — the numbers/keys that must survive the bake)
   │        world · scene · chibi_action · identity_ref (or null → the project's canonical cast)
   │    • render fields: bubbles{zh,en} · caption · safe_zones · crop · text_mode
   ▼
validate: schemas/comic.schema.json  (jsonschema) + cli/validate_wiki.py (the trace, after a run)
   ▼
run_comic.py  →  bakes each panel, gates it cross-model, and writes back image_path /
                 active_attempt_id / wiki_node_id on KEEP. You never fill those.
```

This is a direct mirror of `skills/method-figure/references/blueprint_authoring.md` +
`method_figure_brief.schema.json`. Full field reference for the target IR: [`docs/comic-json.md`](../../../docs/comic-json.md)
+ [`schemas/comic.schema.json`](../../../schemas/comic.schema.json). Your authoring agent can be any coding
agent — e.g. the [**ARIS** main project](https://github.com/wanshuiyin/Auto-claude-code-research-in-sleep),
which can read your source material and emit the `comic_brief` → `comic.json`. **Do not depend on ARIS main at
runtime** though — this repo is self-contained; ARIS main is only an *optional* upstream brief producer.

---

## Two honesty notes (read before you point at the example)

> **① The blueprint is per-figure, and YOU author it.** ARIS-Movie-Director does not invent your content.
> For every panel that carries a technical figure, *you* author a deterministic SVG blueprint
> (`condition.content_svg`) and you declare the numbers/labels/code tokens that must survive the bake
> verbatim (`condition.expected_literals`). The framework only *bakes the look* and then *adversarially
> checks* that your authored numbers actually appear — a beautiful panel whose number is wrong (`+6.2`
> authored vs `+6.25` baked) is rejected by the deterministic token-diff. The blueprint is the **ground
> truth**; the image model is never trusted to originate a number. The examples here use ARIS's own audit
> story, but the path is generic: swap in your SVG and your literals. **Every panel needs a `content_svg`**
> (the engine requires one as the layout/content authority) — a scene-only panel gets a simple *layout*
> blueprint and uses `text_mode: "html"` (no baked-literal contract); do **not** use `content_svg: null`.

> **② Identity is bring-your-own; the ARIS chibi duo is just the example.** The reference movie's
> `executor`/`reviewer` chibi pair and `assets/duo_canonical_ref_v001.png` are **one** identity set, shipped
> so the trace is reproducible — not a required cast. Point each panel's `condition.identity_ref` at *your*
> canonical character sheet (a project-relative `.png`), or leave it `null` to fall back to the project's
> canonical ref. The gate judges identity **against the ref you supply**, per character, and never penalizes
> a character for being absent from a panel (cast-aware). Your characters, your world (`warm-lab` /
> `dark-cyber` are the example's two-world palette — define your own in `ART_BIBLE.md`).

---

## Step-0 mapping (brief → comic.json)
| brief field | → comic.json |
|---|---|
| `beats[]` (id, page_type, members) | `pages[]` (`id`, `type`, `panel_ids`) + `narration`/`beat_title` |
| `cast[]` + `identity_refs` | top-level `identity_refs` + each panel's `condition.identity_ref` |
| per-panel `headline_numbers` / `claims` | the SVG blueprint's drawn text **and** `condition.expected_literals` (verbatim) |
| per-panel `world` | `condition.world` (drives ART_BIBLE §0.5 lighting) |
| per-panel `beat`/`staging` | `condition.scene` + `condition.chibi_action.{executor,reviewer}` |
| per-panel `dialogue` | `bubbles[]` `{speaker, style, text:{zh,en}}` |
| `text_mode intent` | panel `text_mode` (`baked` = dialogue drawn into the image; `html` = HTML bubble overlay) |

**Guardrail (same as the figure side):** every panel's drawn numbers must be copied VERBATIM into
`expected_literals`. A baked figure panel with no ascii-tokenizable `expected_literals` is **refused**
(fail-closed) by `run_comic.py` — there'd be nothing to verify, so a wrong number could slip.

## Worked example (the shipped reference)
Panel **S12** (the `examples/comic_m3_audit` audit page) is the template to copy:
```jsonc
"S12": {
  "text_mode": "baked",
  "crop": { "shape": "wide", "position": [0.5, 0.45], "zoom": 1.0 },
  "bubbles": [
    { "speaker": "executor", "style": "shout", "text": { "zh": "赢了 +6.2！", "en": "We won — +6.2!" } },
    { "speaker": "reviewer", "style": "terse", "text": { "zh": "先审评估器。", "en": "Audit the evaluator first." } }
  ],
  "caption": { "zh": "…", "en": "…" },
  "condition": {
    "content_svg": "assets/method_random_vs_schema_first_v1.svg",   // YOU author this SVG
    "expected_literals": ["+6.2"],                                   // the number that must survive the bake
    "world": "warm-lab",
    "identity_ref": null,                                            // → falls back to the canonical duo
    "scene": "warm-lit pixel ML research lab at night … amber Δ +6.2 callout …",
    "chibi_action": { "executor": "arm thrust up in triumph", "reviewer": "arms crossed, skeptical" }
  }
}
```
Then: `python3 skills/comic-director/scripts/run_comic.py --project examples/<name> --page <P> --panels S12`
→ bakes S12, gates it (the `+6.2` must be transcribed by both visual reviewers), and on KEEP writes its
`image_path` back into `comic.json`.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://github.com/wanshuiyin/ARIS-Movie-Director/skills/comic-director/comic_brief.schema.json",
  "title": "comic_brief — the upstream hand-off (idea → Step-0 → comic.json)",
  "description": "The SEMANTIC brief a USER's agent emits from a fuzzy idea. It decides WHAT the comic depicts; Step-0 compiles it into a schema-valid comic.json (schemas/comic.schema.json); run_comic.py bakes + verifies. Mirrors method_figure_brief.schema.json. See references/comic_authoring.md.",
  "type": "object",
  "required": ["comic_id", "logline", "beats"],
  "properties": {
    "comic_id": {"type": "string", "pattern": "^[A-Za-z0-9_-]+$"},
    "logline": {"type": "string", "description": "one-sentence premise the whole comic must land"},
    "thesis": {"type": "string", "description": "the point a reader should feel by the end"},
    "cast": {"type": "array", "description": "the recurring characters + their locked identity",
      "items": {"type": "object", "required": ["id"], "properties": {
        "id": {"type": "string", "description": "e.g. executor | reviewer | researcher"},
        "identity_ref": {"type": "string", "description": "project-relative .png canonical sheet (BYO; null → project canonical)"},
        "traits": {"type": "array", "items": {"type": "string"}, "description": "locked visual traits, e.g. 'blue hoodie','no beard'"}}}},
    "worlds": {"type": "array", "items": {"type": "string"},
      "description": "the palette/world tags this comic uses (define them in ART_BIBLE.md), e.g. warm-lab, dark-cyber"},
    "beats": {"type": "array", "minItems": 1, "description": "the story beats, in reading order (one per page)",
      "items": {"type": "object", "required": ["id", "panels"], "properties": {
        "id": {"type": "string", "description": "beat/page id, e.g. B02"},
        "page_type": {"enum": ["cover", "single", "grid", "grid2x2", "feature", "finale"], "default": "single"},
        "title": {"type": "object", "properties": {"zh": {"type": "string"}, "en": {"type": "string"}}},
        "narration": {"type": "object", "properties": {"zh": {"type": "string"}, "en": {"type": "string"}}},
        "panels": {"type": "array", "minItems": 1, "items": {"$ref": "#/$defs/panel_brief"}}}}},
    "target_locale": {"enum": ["en", "zh"], "default": "en"},
    "bake_lang": {"enum": ["zh", "en"], "default": "zh", "description": "which dialogue language gets baked into the image"}
  },
  "$defs": {
    "panel_brief": {
      "type": "object",
      "required": ["id", "scene"],
      "properties": {
        "id": {"type": "string", "description": "panel id, e.g. S12"},
        "world": {"type": "string", "description": "which world tag (must be one of brief.worlds)"},
        "scene": {"type": "string", "description": "what's in the panel — props, staging, composition (becomes condition.scene)"},
        "staging": {"type": "object", "properties": {
          "executor": {"type": "string"}, "reviewer": {"type": "string"}},
          "description": "per-character action (becomes condition.chibi_action)"},
        "identity_ref": {"type": "string", "description": "BYO character sheet for this panel; null → project canonical"},
        "figure": {"type": "object", "description": "the technical figure this panel carries (if any)",
          "properties": {
            "blueprint_svg": {"type": "string", "description": "project-relative .svg YOU author = the content authority (→ condition.content_svg)"},
            "headline_literals": {"type": "array", "items": {"type": "string"},
              "description": "the exact numbers/keys/code tokens that MUST survive the bake (→ condition.expected_literals; REQUIRED if blueprint_svg is set)"}}},
        "dialogue": {"type": "array", "items": {"type": "object", "required": ["speaker", "text"], "properties": {
          "speaker": {"type": "string", "description": "a cast id"},
          "style": {"type": "string", "description": "say | shout | terse | thought | whisper"},
          "text": {"type": "object", "properties": {"zh": {"type": "string"}, "en": {"type": "string"}}}}}},
        "text_mode": {"enum": ["baked", "html", "code"], "default": "baked",
          "description": "baked = dialogue drawn into the image; html = HTML bubble overlay in the viewer"}
      }
    }
  }
}