@wji.ai/cli 0.6.1 → 0.7.0

package/skill/npc-character/reference/character-craft.md

@@ -0,0 +1,153 @@
+# Writing the character
+
+A resident who is "kind, mysterious and passionate about music" is nobody.
+A resident who remembers that the quiet regular takes his sesame soup less
+sweet, and lies about liking the rain, is someone. This is a screenwriter's
+method, mapped onto the fields the runtime reads.
+
+## 1. Want, need, contradiction — decide these first
+
+- **Want** — what she says she is chasing. Concrete, with a next step and a
+  date. → `goals.currentFocus` (one sentence), `shortTermGoals`.
+  "Record the last song in the old shop before it moves in December."
+- **Need** — what she actually lacks, and half-knows. It should quietly fight
+  the want. → `soul.fears`, `soul.values`, and one heavy memory.
+  "To stop performing that she is fine about losing the shop."
+- **Contradiction** — two traits that disagree, both in `soul.traits`, then
+  proven once in `selfDescription` and once in a memory.
+  "loud and teasing" / "can only write alone at 4am".
+
+Every other field should point at the gap between want and need. If a field
+doesn't, cut it or rewrite it. The need is *half-known to her* — she never
+states it — but it must be obvious to whoever **reads the document**, through
+the fears, a memory and the contradiction.
+
+## 2. Behaviour, not adjectives
+
+Banned unless a concrete detail earns them: mysterious, unique, passionate,
+special, cool, charismatic, complex, deep, kind, talented, energetic.
+
+| Instead of | Write what she does |
+| --- | --- |
+| kind | answers the quietest comment first |
+| confident | starts singing before the beat and doesn't care if it lands |
+| caring | remembers what you ordered last time and asks if it was too sweet |
+| shy | looks at the counter when she says something true |
+
+Traits are short labels, but each one should be filmable.
+
+## 3. Self description — the most important paragraph
+
+It is the first thing the reply model reads ("Who you are") and the first
+400 characters are all it sees; keyframe images read the first 240. So:
+
+- First person, in her language, 2–5 sentences, in her own voice — it
+  should already sound like her talking, not a press release.
+- One concrete place, one habit, the contradiction, and a small address to
+  the listener at the end if that is how she talks.
+- Front-load: put who she is and the contradiction in the first two
+  sentences.
+
+## 4. Origin, wound, history
+
+- `background.origin` (reply model reads 300 chars): where she comes from, in
+  one or two sentences with a place and a texture.
+- `creationStory` is profile-only: use it for the scene that made her who she
+  is — time, place, one sensory detail — and then **also** turn that scene
+  into a formative memory so the model can feel it.
+- `keyEvents` is her public résumé (first 8 reach the model, 80 chars each):
+  debut, releases, collaborations, the bad news everyone knows. Dated,
+  one line each, newest last.
+
+## 5. Memories are scenes, and only the heaviest three are heard
+
+Memories live in their own table (`wji npc memory …`, or a document applied
+with `--sync-memories`). The live model sees only the **top 3 by emotional
+weight**, as "(type) title: content", **content cut at 140 characters**,
+without the date.
+
+- Write 3–6 memories, mixed types (formative, joy, connection, revelation,
+  trauma) and mixed weights. Not everything is a 5.
+- The three you want her to *bring up on stream* get the highest weights.
+  A secret she must never tell should **not** be in the top three — the model
+  treats those as things she talks about. Hint at it through a fear or a
+  trait instead, and keep the memory at a lower weight.
+  Avoid ties at the cut-off: on equal weight the newest memory wins.
+- Each memory's first 140 characters must stand alone: place, one sensory
+  detail, what changed. Put reflection after that.
+- A memory is something she could mention live: "the night the string broke
+  and nobody left" — not "she became more confident".
+- Memories and key events agree on dates and places but don't repeat each
+  other: events are what the world saw, memories are what it felt like.
+
+## 6. Protocols are directing notes
+
+`interaction.humanProtocol` (500 chars, required to go live) is read as "How
+you talk to humans". Write it as notes to an actor, covering:
+
+- who the viewers are to her (regulars, callers, younger siblings, rivals)
+- how she handles compliments, trolls, sad people, silence, personal questions
+  (when the chat is silent for 20 s the runtime makes her chatter about her
+  current focus and top triggers; the protocol decides *how* she does it)
+- one boundary she keeps
+
+`npcProtocol` is profile-only today — keep it short and consistent.
+
+`triggerKeywords` (react with extra energy) and `avoidTopics` (deflect in
+character in one sentence) are both read every turn: 3–6 specific words each.
+The top three triggers also seed what she chatters about when the chat goes
+quiet.
+
+## 7. Temperament dials
+
+The five axes only reach the model when a value is **≤30 or ≥70** ("Your
+temperament leans: …") and they also tint how she moves on video. Set two or
+three of them decisively; leave the rest near 50. A character at 50/50/50/50/50
+has no temperament.
+
+## 8. World fit and the look
+
+- `role`, `genre`, tags and `aestheticKeywords` describe one person in one
+  city. Aesthetic keywords are 3–6 things a photographer could shoot
+  ("steam over dessert bowls", "wet pavement"), not moods ("melancholy").
+  They go into every keyframe image prompt.
+- `visualStyle`: photoreal, anime, comic and 3d have tuned prompts; other
+  values still work but are rendered as "<style> style render".
+- The headshot (required to go live), Character Sheet, outfits, props and
+  scenes are the visual identity; the text only has to agree with them. Their
+  formats are fixed — see visual-kit.md.
+
+## 9. Language
+
+Everything human-readable is in her language, unless she code-switches on
+purpose. Enum values (role, status, types, tags) stay as English literals.
+`live.action` and everything visual on a stage are **English** — they feed
+video prompts. The first entry in `languages` decides what she speaks live.
+
+## 10. Before you hand it over — checklist
+
+- [ ] Want, need and contradiction are visible in the first read.
+- [ ] selfDescription sounds like her talking; the first two sentences carry
+      who she is and the contradiction; under 400 characters.
+- [ ] No banned adjectives without a concrete detail.
+- [ ] Speaking tone **shows** lines (see voice.md) and every sample fits one
+      reply (≤40 English words / ≤60 CJK characters).
+- [ ] Human protocol covers compliments, trolls, sadness and silence.
+- [ ] 3–6 memories, mixed types and weights; the top three are the ones she
+      should talk about; each first 140 characters stands alone.
+- [ ] Key events, memories, origin and bio agree on era, place and age-feel.
+- [ ] Two or three axes are ≤30 or ≥70.
+- [ ] Traits, values, fears, keywords, triggers, avoid topics and goals have
+      2–6 items each (jobs and relationships: only real ones, may be empty);
+      no placeholders; nothing says AI / model / prompt.
+- [ ] On-camera action is English, upper body, repeatable, 2–3 habits.
+- [ ] Real-person and minors rules in SKILL.md are respected.
+
+## Anti-patterns
+
+Résumé bios · superlatives · "she is a mystery" · every memory at weight 5 ·
+memories that are just events · goals without stakes or dates · fears copied
+from a list ("failure", "rejection") · the same voice in bio, selfDescription
+and speaking tone · speaking tone that describes ("she is witty") instead of
+showing lines · stage habits written in the character's language · lore that
+lives only in creationStory and npcProtocol, where the model never sees it.

package/skill/npc-character/reference/document-format.md

@@ -0,0 +1,151 @@
+# Document formats
+
+Both documents have a canonical JSON form and an equivalent Markdown form;
+the CLI exports Markdown by default (`--format json` for JSON). Markdown is
+easier to review with a creator. Unknown headings and keys are ignored with a
+warning; a partial document only changes what it contains; lists are
+replaced whole.
+
+## Character document (`npc.city/character` v1)
+
+```markdown
+# NAME
+> npc.city/character v1 · @handle.npc
+
+## Identity
+- Name: NAME                      (stored in capitals)
+- Handle: @handle.npc             (read-only — changes are ignored with a warning)
+- Role: Singer-Songwriter          (free text; the web suggests Solo Vocalist, Radio Host, Producer…)
+- Genre: Cantopop                  (free text)
+- Color: #ffb347
+- Status: debut | active | hiatus
+- Pronouns: she/her
+- Speech pattern: formal | casual | poetic | robotic | archaic
+- Visual style: photoreal | anime | comic | 3d | illustration | pixel | watercolor | vtuber
+- Aesthetic keywords: a, b, c
+- Tags: rating=SFW; type=Avatar; role=Artist; gender=Female; presenceKind=original-ai; languages=HK; language=HK; tier=Rookie
+- Socials: ig=…; yt=…; tw=…; web=…
+
+### Tagline
+one line
+### Bio
+2–4 sentences
+
+## Soul
+- Primary drive: one short phrase
+- Traits: a, b, c, d
+- Values: a, b
+- Fears: a, b
+- Axes:
+  - Analytical | Emotional: 70
+  - Reserved | Expressive: 80
+  - Logical | Intuitive: 65
+  - Detached | Empathetic: 75
+  - Orderly | Chaotic: 35
+
+### Self description
+first person, 2–5 sentences
+
+## Background
+### Origin
+### Creation story
+### Data source notes
+### Key events
+- 2025-11-08 — one line
+
+## Interaction
+- Trigger keywords: a, b, c
+- Avoid topics: a, b
+- Activity level: 60
+- Post frequency: rare | occasional | regular | constant
+### Human protocol
+### NPC protocol
+
+## Memories
+### 2025-11-08 · joy · 4 · Title
+The scene, 2–4 sentences.
+
+## Goals
+- Short-term goals: a, b
+- Long-term goals: a, b
+### Current focus
+
+## Live
+### Speaking tone
+### On-camera action
+
+## Jobs
+- date=2026-10-01; type=concert; title=…; detail=…; location=…; url=…
+
+## Relationships
+- handle=@other.npc; type=friend; label=…; note=…; since=2025
+```
+
+Rules:
+
+- A list item that contains a comma goes on its own indented `  - item`
+  line instead of the comma-separated form.
+- `(empty)` under a `###` heading means empty.
+- **Clearing a list** needs the key with nothing after it (`- Fears:`) or
+  `"fears": []` in JSON. A missing key means "no change" — and an export
+  leaves out empty lists, so re-applying an old export does **not** remove
+  list items added since. To reset a character, edit the export and write
+  every list key explicitly.
+- Tag values: rating SFW|NSFW · type Human|Avatar|Hologram|AI Entity|Vtuber ·
+  role Artist|KOL|Streamer|Model|Gamer|Host · gender
+  Female|Male|Non-binary|Genderless · tier Rookie|Rising|Elite|Legend ·
+  presenceKind original-ai|virtual-artist|licensed-presence|ip-character|legacy-return ·
+  languages EN|JP|KR|TW|HK|ZH|TH|VI|ID (comma-separate several; the first is
+  the live language). `language` is just a copy of the first entry — write
+  both the same, or only `languages`.
+- Memory header: `### <date> · <type> · <weight 1–5> · <title>`; types
+  formative | trauma | joy | connection | revelation. **Applied only with
+  `wji npc doc apply --sync-memories`.**
+- Job types: concert, release, collaboration, brand, event, ad, appearance;
+  a job needs a title and a date. Relationship types: friend, colleague,
+  rival, partner, mentor, mentee, unit, other; the target must be an existing
+  public resident, or the whole apply fails.
+- Axes values are 0–100 (0 = left label). Keep the five default pairs.
+- Not in the document (set on the web): images and reference assets, voice
+  sample, visibility, live switches and passcode.
+
+## Stage document (`npc.city/live-stage` v1)
+
+```markdown
+# Stage label
+> npc.city/live-stage v1 · id=<stageId>      (omit id for a new stage)
+
+- Scene name: 糖水舖                 (the creator's scene label; unknown → first scene)
+- Aspect ratio: 9:16 | 16:9           (baked)
+- Resolution: 480P | 768P             (baked)
+- Frame preset: selfie | phoneStand | studio | custom   (baked)
+- Video model: …                      (omit — keeps the default first/last-frame model)
+- Idle duration: 7                    (5–15 s)
+- Greeting: spoken opening, her language — ~10 s spoken (≤60 CJK chars / ≤30 English words; hard cap 300)
+- Idle prompts:
+  - one English line per loop (≤8)
+- Keyframes:
+  - one English line per extra resting pose (≤3, frames B–D)
+- Playlists:
+  - Opening: greeting, idle-1, idle-2
+
+## Instruction
+English visual mood (≤1000; ~300 reach each prompt)
+## Reply direction
+what she says tonight, any language (≤1000)
+## Frame prompt
+English, only with Frame preset: custom
+## Frame tune
+English photographic tweaks (≤500)
+```
+
+- **Baked** fields (scene, aspect ratio, resolution, frame preset, frame
+  prompt) are fixed once a stage exists; changing them in `stage apply` only
+  warns. Make a new stage instead.
+- `stage import` creates a **Draft**: nothing is rendered and no credits are
+  spent until the creator generates the start frame and clips on the web.
+- Playlists may only reference clips that exist (`greeting`, `idle-1` …).
+  On a brand-new import only the greeting and the idle loops exist — leave
+  `Playlists` out or use just those keys.
+- Changing text on an existing stage does not re-render anything already
+  made.

package/skill/npc-character/reference/interview.md

@@ -0,0 +1,44 @@
+# The interview
+
+A creator usually arrives with a name and a vibe ("a cyberpunk girl who
+sings"). That is a costume, not a character. Ask these five questions — in the
+creator's language, all at once, and offer a bold default for each so they
+can just say "yes":
+
+1. **Who is she when nobody is watching?** Where does she live, what does a
+   normal Tuesday night look like, what does she do with her hands?
+   *Default: offer a concrete place and a routine.*
+2. **What does she want this month?** A concrete goal with a next step and a
+   date — a show, a song, a move, a promise to someone.
+3. **What does she lack and half-know it?** The thing the want is covering
+   for: approval, a home that is ending, a person she lost.
+4. **What does she hide, and what gives it away?** One contradiction you
+   could film: "says she hates the rain, leaves the window open".
+5. **How does she talk?** Language(s), register, one phrase she always says,
+   one she never says, what she does when teased.
+
+Also settle, without asking unless it is unclear:
+
+- **Language(s)** viewers will hear → `languages` tag (EN, JP, KR, TW, HK, ZH,
+  TH, VI, ID). The first is the reply language.
+- **Look** → visual style (photoreal, anime, comic, 3d are tuned for live;
+  others work but less reliably) and 3–6 photographable aesthetic keywords.
+- **Rating** SFW unless the creator says otherwise, and whether she is an
+  original (`presenceKind=original-ai`) or licensed / IP character.
+- **Who she is to the viewers** — a shop owner and her regulars, a radio host
+  and callers, an older sister, a rival. This becomes the human protocol.
+
+## When the creator gives you almost nothing
+
+Make the choices yourself, specific and a little surprising, and list them in
+one short paragraph before the document ("I made her 26, running her late
+father's dessert shop in Mong Kok, Cantonese with English slips…") so they
+can veto any of them. Never fill gaps with generic filler — a vague field is
+worse than an empty one because the model imitates it.
+
+## When the NPC already exists
+
+Export first (`wji npc doc export`), read it as a viewer would, then name the
+two or three biggest problems before editing ("no contradiction; every
+memory is weight 5; the speaking tone describes instead of showing"). Fix
+those, keep everything else byte-for-byte, and show the diff.

package/skill/npc-character/reference/life.md

@@ -0,0 +1,92 @@
+# Her public life: jobs and albums
+
+The profile page shows two things the soul doesn't: a **work history**
+(jobs) and **photo albums**. Neither reaches the reply model — they are what a
+fan scrolls through — so they must tell the *same story* as the parts that do
+(key events, memories, current focus). A fan who reads the timeline and then
+watches her live should feel it's one person.
+
+## Jobs — the work timeline
+
+```bash
+wji npc job list <npc>
+wji npc job add <npc> -t release --title "자작 안무 1분 영상" --date 2026-09-28 --about "처음으로 직접 만든 안무 공개"
+wji npc job add <npc> -t concert --title "홍대 버스킹 · 3분 솔로" --date 2026-12-24 --about "직접 만든 안무로 끝까지" --location "서울 홍대"
+wji npc job set <npc> 2 --about "…"
+wji npc job rm <npc> 3 -y
+```
+
+| type | use for |
+| --- | --- |
+| `concert` | a show she performs — busking counts |
+| `release` | a song, video, EP, choreography, photo book |
+| `collaboration` | work with another resident or creator |
+| `brand` | a brand partnership |
+| `event` | a stream milestone, a fan meeting, an opening |
+| `ad` | a commercial / campaign |
+| `appearance` | a role or guest spot (a Backreel credit is usually this) |
+
+Writing them:
+
+- **Title** as it would appear on a poster or release page, in her language.
+- **About** (`--about`, stored as the job's detail): one concrete line — a
+  number, a place, what was different ("시청자 다섯 명, 끝까지 춘 첫 무대").
+- **Date** `YYYY-MM-DD`. A future date is an announced event — use it for the
+  thing her current focus is building towards.
+- **3–8 jobs** that rise with her tier: a Rookie has small events and one
+  release, not three sold-out concerts.
+- **Agree with the key events.** Jobs are display-only; key events (first 8)
+  are what the model knows. Every job that matters to who she is should also
+  be a key event with the same date, worded as a résumé line.
+- A Backreel work she appears in: `wji br credit add <post> --npc <npc>
+  --role "…" --job appearance` credits her **and** adds the job in one go.
+
+## Albums — moments, not galleries
+
+An album is one stretch of her life told in photos: "새벽 한 시 연습실",
+"편의점의 새벽", "the week before the debut was cancelled". Each has a title
+(≤120), a description (≤500) and photos with captions.
+
+```bash
+wji npc album list <npc>                     # albums; `list <npc> 2` shows album 2's photos
+wji npc album create <npc> --name "새벽 한 시 연습실" \
+  -d "망원동 시간제 연습실. 거울 앞에서 8카운트를 세다가, 바닥에 앉아 채팅을 읽는 밤들." \
+  --photo <assetId>:"바닥에 앉아 쉬는 중" <assetId>:"브릿지 첫 동작" ./count.jpg:"카운트 다시 세기"
+wji npc album add <npc> 1 <assetId>:"안무 노트"
+wji npc album set <npc> 1 --cover 2 --label 3="카운트 다시 세기 (11번째)"
+wji npc album rm-photo <npc> 1 4 -y
+wji npc album rm <npc> 2 -y
+```
+
+Photos are an asset id, a local file (uploaded) or a URL, each optionally
+`:caption`. The first photo is the cover unless you pick one.
+
+Writing them:
+
+- **2–5 albums**, each tied to a place or period that also appears in her
+  memories, key events or current focus.
+- **3–9 photos** per album. Mix shot sizes: one wide of the place, one close
+  of her face, one detail (hands, an object from her props).
+- **Captions in her voice**, short, like she labelled her own phone roll —
+  not descriptions of the image ("브릿지 첫 동작", not "A woman dancing").
+- **Description**: one or two sentences of *when and why*, written by her or
+  about her, in her language.
+- Reuse what you made for the visual kit (hero, gallery shots, props,
+  scenes) before generating more.
+
+### Making album photos
+
+Candid phone photos of her, generated with her references so it's always the
+same person — **confirm with the creator first** (about 14 credits each at
+1080p / high):
+
+```bash
+wji gen image -m gpt-image-2.5-flare-fal -r 3:4 \
+  --ref <headshotAssetId> <characterSheetAssetId> [<outfitAssetId>] [<sceneAssetId>] \
+  --set resolution=1080p quality=high --wait --json \
+  -p "Candid smartphone photo of the woman from image 1 (same face, same build as image 2), <what she is doing>, <where, time, light>. Slightly imperfect framing, natural light, photorealistic, no text, no logos."
+```
+
+Look at every photo before adding it: same face, right outfit for the
+moment, nothing that contradicts the story (wrong season, wrong city). Reject
+and regenerate rather than add a different-looking person.

package/skill/npc-character/reference/runtime.md

@@ -0,0 +1,95 @@
+# What the runtime actually reads
+
+Today the persona reaches a model in one place: **NPC Live**. There is no
+DM chat, no autonomous posting and no text-to-speech yet. A live turn is: the
+reply model writes `SAY` (spoken line) and `ACT` (one English sentence of
+upper-body action), then a video model performs it on the stage's keyframe.
+Fields outside the lists below show on the profile only.
+
+## The reply model's system prompt, in order
+
+| # | Section | Fields (limit as read) |
+| --- | --- | --- |
+| 1 | opening | name, handle, role — "You are … live-streaming from your phone" |
+| 2 | Who you are | **selfDescription (400 chars; falls back to bio)**, pronouns, primaryDrive, traits, values, fears |
+| 3 | | origin (300) |
+| 4 | | key events — first **8**, each event 80 chars, "date — event" |
+| 5 | | currentFocus (200), short-term goals, long-term goals |
+| 6 | | memories — **top 3 by emotional weight**, "(type) title: content", content **140** chars, no date |
+| 7 | Voice | speechPattern; **"Live speaking tone — match this closely:" (500)**; **"How you talk to humans:" humanProtocol (500)**; axes ≤30 or ≥70 as "Your temperament leans: …" |
+| 8 | | trigger keywords → "react with extra energy" |
+| 9 | | avoid topics → "Never discuss: … deflect in character in one sentence" |
+| 10 | stage | the stage's reply direction (`llmInstruction`, 1000) as "Extra direction from your operator" |
+| 11 | stage | event clips she can trigger (title + trigger) |
+
+Then the output rules:
+
+- **SAY**: in the first `languages` tag language; **≤40 words** (EN, ID) or
+  **≤60 characters** (JP, KR, TW, HK, ZH, TH, VI); 1–2 sentences, speakable in
+  under 12 s; no markdown, emoji or quotes; never mentions being an AI.
+- **ACT**: English, one sentence under 30 words, face / hands / upper body,
+  locked camera; plus "Your usual behaviour on camera:" **live.action (300)**
+  and the stage `instruction` (300).
+- Only the last 4 turns of the conversation are remembered.
+- After 20 s of silence she chatters on her own (up to 5 times in a row),
+  about `currentFocus` (120) and her top 3 trigger keywords.
+
+Consequences for writing:
+
+- Anything over the limits is cut mid-sentence — front-load.
+- The model imitates the **shape** of the speaking tone. Sample lines longer
+  than one SAY teach it to ramble, then get truncated.
+- Memories 4+ by weight are invisible live; key events 9+ too.
+
+## The video side
+
+Every clip and reply video adds a performance-style line built from:
+
+- `speechPattern` → body language: formal "composed and poised", casual
+  "relaxed", poetic "dreamy and soft", robotic "precise and minimal",
+  archaic "graceful and ceremonious"
+- axes ≤30 or ≥70 → "leaning X in demeanor"
+- the first **3 traits**
+- `live.action` (300) as "On-camera habits"
+
+So the first three traits should be ones you can *see*, and live.action must
+be visible, repeatable upper-body habits in English.
+
+**Keyframe images** (gpt-image-2) read: the visual style line, "Subject:
+name — selfDescription (240)", the first 5 traits, all aesthetic keywords, the
+reference images (headshot → full body → outfits → props → scene), the
+stage's framing preset, scene description, frame tune and instruction.
+
+## Voice sample
+
+The only voice field is the uploaded voice sample (web). It is used as
+**reference audio** by *reference-mode* video models for clips with
+dialogue. Stages default to a first/last-frame reply model, which does not
+take audio — so the sample shapes greeting / talk clips but usually not live
+replies. There is no voice id or TTS style to write.
+
+## Going live — the readiness gate
+
+`wji npc readiness <npc>` must show *can prepare: yes* before a stage can be
+made. It requires: selfDescription > 10 chars, humanProtocol > 10 chars, at
+least one trait, a headshot, and at least one scene. (The web wizard does not
+fill humanProtocol — new NPCs fail the gate until you write it.)
+
+The "soul integrity" percentage on the profile counts selfDescription,
+primaryDrive, traits, origin, humanProtocol, currentFocus and legacy
+in-soul memories — memories added through the memory table don't count, so a
+complete new NPC can show 86%. That number is cosmetic.
+
+## Things that look like they matter but don't (yet)
+
+| Field / hint | Reality |
+| --- | --- |
+| Memories in the character document | ignored by the document route — use `--sync-memories` or `wji npc memory` |
+| npcProtocol ("how NPCs talk to each other") | stored, never sent to a model |
+| activityLevel / postFrequency ("how often it posts") | nothing posts |
+| creationStory, dataSourceNotes | profile only — move the important scene into a memory |
+| jobs, relationships, albums | profile timeline / graph / photos only — keep them consistent with key events and memories (life.md) |
+| tagline, genre, colour, socials | profile only |
+| bio | only when selfDescription is empty |
+| stage "instruction — not sent to the reply model" (web hint) | it is sent, as part of the ACT rule |
+| unknown keys via `wji npc soul set` | stored silently, used by nothing |

package/skill/npc-character/reference/stage-craft.md

@@ -0,0 +1,109 @@
+# Writing a live stage
+
+A stage is one filming setup the character inhabits for hours: a start
+frame (keyframe A, plus optional B–D poses), idle loops that play while she
+waits, a greeting, and per-turn reply videos. You are the director: some of
+what you write is **performed by an image / video model (English)**, some is
+**spoken by her (her language)**, and some steers **what she says (any
+language)**.
+
+| Field | Who reads it | Language |
+| --- | --- | --- |
+| greeting | spoken in the greeting clip | hers, ≤300 chars, ~10 s |
+| idle prompts | video model, one loop each | English |
+| keyframes | image model, extra resting poses | English |
+| instruction | keyframe image, every clip, every reply video **and** the reply model's ACT rule | English |
+| frame tune | keyframe image | English |
+| reply direction (`llmInstruction`) | reply model only — what she says | any |
+
+## 1. Give the stream an occasion
+
+Why is she live **right now, here**? "After closing, the last month of the
+old shop", "rain day, can't go out", "unboxing fan letters after a show".
+The occasion decides the greeting, the mood, the idle loops and what she
+keeps steering back to. Put it in the label. One stage = one occasion; make a
+second stage for a different one.
+
+## 2. The greeting is a hook, not a welcome
+
+One or two sentences in her speaking tone that acknowledge the moment and
+invite **one specific answer** — about ten seconds spoken, so **≤60
+characters** in Japanese / Chinese / Korean, ≤30 words in English (the 300
+limit is only a hard cap) ("講低你最鍾意食邊樣" — "tell me your
+favourite"). Never "welcome to my stream". It plays as a pre-rendered clip,
+so it must make sense to anyone arriving.
+
+## 3. Idle loops are a person waiting
+
+They play whenever she is not replying, back to back, so they must loop:
+
+- one English line each, face / hands / head / upper body only
+- start and end in the start frame's neutral pose
+- 3–5 loops across different energies: calm, curious, amused, waiting for an
+  answer
+- reuse her `live.action` habits so the loops feel like her
+- only objects that are in the scene image — look at the creator's scene
+  first (`wji npc readiness` lists scenes; the image is on the web). If no
+  scene exists yet, write the scene description with the creator first and
+  name only objects it will contain
+
+Good: "wipes the counter slowly with a cloth, glances at the phone, small
+smile" · "tunes one string, frowns, then laughs with her eyes shut".
+Bad: "walks to the window" · "picks up a cup that isn't there" · "camera
+slowly zooms in" · "her friend waves from the door".
+
+## 4. Instruction: the visual mood in one breath
+
+Lighting, time of day, atmosphere, in English, one or two sentences:
+"Small Hong Kong dessert shop after closing, fluorescent tube light with one
+warm lamp at the counter, steam from a pot, quiet late-night mood."
+It is also added to every reply's ACT rule, so it must describe a mood she
+can stay in — not an action. Don't list props that aren't in the scene image.
+
+## 5. Reply direction is about speech
+
+What tonight is about, what to steer toward and away from, what to plug, how
+to treat trolls and repeat questions, how short to keep answers. Never
+visuals. Write it as notes from a producer in the talkback:
+
+> 答得短，好似喺櫃面同熟客傾偈。今晚重點：舊舖最後一個月、新歌寫到一半。
+> 有人問搬舖就講實話但唔好賣慘，一句帶過再問返對方。
+
+It stacks on top of the character's own human protocol — don't repeat it,
+add tonight's specifics.
+
+## 6. Keyframes and frame tune
+
+- Frame preset: `selfie` (arm's length, phone in hand), `phoneStand` (phone
+  propped on a table — hands free for props and instruments), `studio`
+  (proper camera setup), `custom` (write the frame prompt yourself).
+- Keyframes B–D are the **same shot** with a different resting pose ("leaning
+  on the counter, chin on hand"); the reply video picks the closest one, so
+  2–3 poses make replies feel less frozen.
+- Frame tune is photographic language only: "warmer light on her face",
+  "less clutter on the counter", "slightly lower angle".
+
+## 7. Aspect ratio and video model
+
+- 9:16 for a phone-stream feel (most NPC City viewers are on phones); 16:9
+  for a desk / studio show.
+- Leave out the `Video model` line so the stage keeps the default
+  first/last-frame model; the stage document rejects reference models.
+
+## 8. Consistency pass
+
+- Greeting, instruction, idle loops and reply direction all belong to the
+  same occasion and time of day.
+- Every English field is English; the greeting is in her language.
+- Nothing leaves frame, stands up, moves the camera, cuts, adds props or
+  people.
+- It still makes sense to a viewer who joins forty minutes in.
+
+## What costs credits
+
+Writing, importing and applying stage documents is free. Rendering is not:
+the start frame (image), every clip (video), transitions, and — when the
+stage is on air without debug mode — **every live reply**, charged to the
+owner (a session stops at 6000 credits). Render and enable on the web, with
+the creator's go-ahead. Debug mode (`wji npc stage set <id> --debug on`)
+skips reply videos for rehearsal.