@wji.ai/cli 0.6.1 → 0.7.1

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.

package/skill/npc-character/reference/visual-kit.md

@@ -0,0 +1,81 @@
+# The visual kit — formats per slot
+
+The NPC City configure page has one AI-image slot per asset, each with a fixed
+format and layout. Generate to **these** formats (they mirror the web app's
+`build-image-prompts.ts`), or the assets look wrong next to the ones the
+creator makes on the web and the live keyframes get worse references.
+
+| Slot (web label) | Soul field | Ratio | Layout |
+| --- | --- | --- | --- |
+| Headshot | `assets.headshotAssetId` / `headshot` (+ profile `image`) | **1:1** | shoulders up, face clearly visible, clean background |
+| **Character Sheet** | `assets.fullBodyAssetId` / `fullBody` | **16:9** | left third: large headshot · right two-thirds: **front, back, side** full-body views in one outfit · neutral studio background |
+| Outfit | `assets.outfits[]` | **3:4** | **OOTD flat lay**: top-down, garments only (not worn), whole ensemble with shoes and accessories |
+| Prop | `assets.props[]` | 1:1 | product-style, materials and scale readable |
+| Scene | `assets.scenes[]` | **16:9** | environment / backdrop, no people |
+| Profile / hero | profile `heroImage` | 16:9 (9:16 mobile) | character in her world, explicit camera (shot, lens, angle, depth of field) |
+
+Every prompt carries the style line for the NPC's `visualStyle`; for
+photoreal it is: *photorealistic real person (真人), live-action photography —
+not anime, not illustration, not 3D render*.
+
+## Order and references
+
+1. **Headshot first** — every other image of her references it. If a good
+   portrait comes out in the wrong ratio, crop it to 1:1 rather than
+   regenerating (same face, no credits): `sips --cropToHeightWidth 1440 1440
+   --cropOffset 120 0 in.jpg --out out.jpg`.
+2. **Character Sheet** with the headshot as image 1. The live model treats it
+   as "full-body / outfit sheet — match the proportions", so the outfit on the
+   sheet is her default look.
+3. **Outfits**: generate (or photograph) the outfit, then make the flat lay
+   from it ("Transform the clothing from the reference image into an OOTD
+   flat lay…"). A stage can attach up to 6 outfits / props.
+4. **Scenes** at 16:9 even for 9:16 stages — the scene is a reference image,
+   the stage's frame preset decides the shot. A stage copies its scene when it
+   is created: after replacing a scene image, re-import (or recreate) a draft
+   stage so it uses the new one.
+5. Props and hero last.
+
+## Prompt templates (photoreal)
+
+```text
+Character reference sheet, 16:9 horizontal com card / model sheet layout, <style line>.
+Left third: one large portrait headshot — face, hair, and expression clearly visible, matching the reference headshot (image 1).
+Right two-thirds: three full-body standing views in a row — front view, back view, side profile — same outfit, proportions, and appearance across all panels.
+Clean neutral studio background, evenly spaced figures, professional reference sheet layout.
+Character: <who, age-feel, build, hair>. Signature look: <outfit, shoes, accessories>. No text labels, no logos.
+```
+
+```text
+Transform the clothing from the reference image (image 1) into an OOTD flat lay outfit photo, <style line>.
+Top-down bird's-eye view of the complete ensemble neatly arranged on a clean neutral surface — shirt/top, pants/skirt, outerwear, shoes, and accessories laid out as a coordinated outfit-of-the-day flat lay.
+Garments only, not worn by a model; clear fabric texture, silhouette, and styling visible from above.
+The outfit: <pieces>. No text, no logos.
+```
+
+```text
+Environment / scene background, <style line>. Atmospheric composition suitable as a character backdrop. <place, time, light, 3–5 concrete objects that the stage will mention>. No people, no readable signs, no logos.
+```
+
+```bash
+wji gen image -m gpt-image-2.5-flare-fal -r 16:9 --ref <headshotAssetId> \
+  --set resolution=1080p quality=high --wait --json -p @sheet-prompt.txt
+```
+
+About 14 credits per image at 1080p / high — **confirm with the creator
+before generating**, and look at every result before attaching it (faces
+drift; reject and regenerate rather than attach a different face).
+
+## Attaching
+
+```bash
+wji npc soul get <npc> > soul.json          # edit assets, keep album/albums out
+wji npc soul set <npc> @assets.json         # {"assets": {...}} — replaces the whole assets object
+wji npc set <npc> --image <headshotAssetId> --hero-image <heroAssetId> --set 'gallery=["url1","url2"]'
+```
+
+`assets` is replaced as a whole by `soul set`, so always start from the
+current one. Outfit / prop / scene entries are
+`{id, assetId, name, url, description, referenceRole: outfit|prop|location}`;
+names and descriptions are shown to the creator and scene descriptions go into
+keyframe prompts.

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

@@ -0,0 +1,101 @@
+# Voice: speaking tone and on-camera action
+
+## Speaking tone (`live.speakingTone`, 500 chars, her language)
+
+The reply model is told to "match this closely", and it copies what you
+**show** far better than what you describe. A good speaking tone has:
+
+1. **Register in one line** — "Cantonese with English slips, short sentences,
+   like talking across a shop counter."
+2. **One catchphrase** she really uses, in quotes.
+3. **One thing she never says**, and why ("never says 加油 — too lazy").
+4. **How she takes a compliment / a tease** — with the line she'd say.
+5. **Two or three sample lines**, each short enough to be one live reply:
+   ≤40 words in English / Indonesian, **≤60 characters** in Japanese, Korean,
+   Chinese, Cantonese, Thai, Vietnamese.
+
+Before: "She is witty and warm, speaks casually and likes to tease people."
+After: "Cantonese with a few English words, short lines, like at the shop
+counter. Catchphrase「糖水都要趁熱食啦」. Takes compliments by deflecting:
+「得啦得啦，你想我送多碗咩」. Never says「加油」. e.g.「你今晚食咗咩？唔好話我知係杯麵。」"
+
+`speechPattern` (formal / casual / poetic / robotic / archaic) is the coarse
+register **and** her body language on video (formal "composed and poised",
+casual "relaxed", poetic "dreamy and soft", robotic "precise and minimal",
+archaic "graceful and ceremonious"). When the two pull apart — a polite
+speaker who slouches — choose for the body, and let the speaking tone carry
+the politeness.
+
+## Code-switching
+
+If she mixes languages, write the rule *and* show it:
+
+- **Hong Kong**: Cantonese grammar and particles (啦、喎、咩、囉) with English
+  nouns and fillers ("OK", "chill", "send 我"). Write in written Cantonese
+  (嘅、咗、唔、佢), not standard written Chinese, or she will sound like a
+  newsreader. Set `languages=HK`.
+- **Taiwan**: Mandarin with Taiwanese particles (欸、啦、齁) and occasional
+  Taiwanese Hokkien / Japanese loanwords; traditional characters. `languages=TW`.
+- **Japanese**: decide politeness (です／ます vs plain), first-person pronoun
+  (私、あたし、僕、俺, or her own name), and any sentence-final habit.
+  `languages=JP`.
+- **English**: dialect and rhythm matter more than slang — "British, dry,
+  understated" vs "SoCal, fast, lots of 'like'". Avoid dated slang lists.
+
+The first `languages` entry is what she speaks live; add a second only if
+she really answers in it.
+
+## Lines that work live
+
+A live reply is one or two sentences, spoken in under 12 seconds, reacting
+to one viewer. So sample lines should:
+
+- react to the person (use what they said; address them the way she
+  would — "you", a nickname habit, "ラジオネーム…さん"), then
+- add one beat of her (an opinion, a callback, a question back).
+
+Bad: long monologues, lists, lines that need context the viewer doesn't
+have, emoji and stage directions inside the line. Don't invent viewer names
+inside sample lines — the model will greet strangers by them; the runtime
+supplies the real viewer's name when it wants her to use it.
+
+## Human protocol vs speaking tone
+
+- Speaking tone = **how** she sounds.
+- Human protocol = **what she does** with people: regulars vs newcomers,
+  compliments, trolls, sadness, silence, personal questions, a boundary.
+
+Don't repeat one in the other.
+
+## On-camera action (`live.action`, 300 chars, ENGLISH)
+
+2–3 physical habits tied to emotion, performed by a video model on a locked
+camera:
+
+- visible, upper body only: hands, face, head, shoulders, objects already in
+  frame
+- repeatable — they will recur in many clips
+- tied to a feeling: "laughs with her eyes shut", "rests her chin on the
+  guitar when listening", "taps the table twice when excited"
+
+Never: walking, standing up, turning away, leaving frame, camera moves, new
+props, other people. Never write it in the character's language — it is a
+video prompt.
+
+## Making the voice sample
+
+The voice sample is uploaded or set on the soul (`voiceSample`). The cheap way
+to make one is **Seed Audio 1.0** with the headshot as the voice reference —
+about 45 credits a minute, so a 3-second sample costs a few credits (MiniMax
+speech is a flat ~300 per line). Write a bracketed direction in her language,
+then one new 8–12-character line; the bracket is followed, not spoken.
+**Confirm with the creator before generating.**
+
+```bash
+wji gen audio -m "Seed Audio 1.0" --ref <headshotAssetId> -n 2 --wait --json \
+  -p "（27세 여성; 전직 연습생; 맑지만 살짝 허스키한 음색; 중간 음높이; 약간 빠르고 숨이 찬 말투; 표준 서울말; 지쳤지만 단단한 감정; 건조한 목소리, 배경음악과 효과음 없음）오늘은 한 번만 더 해 볼게요"
+wji npc soul set <npc> '{"voiceSample":{"assetId":"<audioAssetId>","url":"<url>","label":"…","durationSec":3.2}}'
+```
+
+Listen to both takes and keep the one that sounds like her speaking tone.
+

package/skill/wji/SKILL.md

@@ -473,7 +473,7 @@ wji npc set @mika --tagline "…" --tag tier=Rising --social ig=https://…
 wji npc publish @mika                          # visibility public (unpublish = private)
 wji npc job add @mika -t concert --title "Neon Night" --date 2026-10-01 --location Taipei
 wji npc job set @mika 2 --detail "sold out" ; wji npc job rm @mika 3 -y
-wji npc soul get @mika > soul.json ; wji npc soul set @mika '{"voice":{…}}'
+wji npc soul get @mika > soul.json ; wji npc soul set @mika '{"liveSpeakingTone":"…"}'   # keys must be soul keys — unknown ones are stored silently
 wji npc doc export @mika -o mika.md            # whole character in one file
 wji npc doc apply @mika @mika.md --dry-run     # see the diff, then without --dry-run
 ```

package/skill/wji/reference/commands.md

@@ -256,17 +256,29 @@ unknown `@handle` falls back to `GET /npc-city/residents/by-handle/:h` (public).
 | `npc rm <npc> [-y]` | `DELETE /npc-city/residents/:id` (soft delete) |
 | `npc handle <handle> [--exclude <npc>]` | `GET /npc-city/residents/handle-available` |
 | `npc job list <npc>` | the resident's `jobs[]`, numbered 1…n |
-| `npc job add <npc> -t <type> --title --date YYYY-MM-DD [--detail] [--location] [--url]` | read, append, `PATCH {jobs}` |
+| `npc job add <npc> -t <type> --title --date YYYY-MM-DD [--about] [--location] [--url]` | read, append, `PATCH {jobs}` |
 | `npc job set <npc> <n> [same flags]` | read, merge into #n, `PATCH {jobs}` |
 | `npc job rm <npc> <n...> [-y]` | read, drop, `PATCH {jobs}`; refuses if the list changed meanwhile |
 | `npc soul get <npc>` | `GET /npc-city/residents/:id/soul` |
 | `npc soul set <npc> <json\|@file\|->` | `PATCH /npc-city/residents/:id/soul {soulConfig}` (shallow merge) |
 | `npc doc export <npc> [--format md\|json] [-o file]` | `GET /npc-city/residents/:id/document?format=` |
-| `npc doc apply <npc> <@file\|-> [--dry-run] [-y]` | `POST …/document/preview`, confirm, `POST …/document` |
+| `npc doc apply <npc> <@file\|-> [--dry-run] [--sync-memories] [-y]` | `POST …/document/preview`, confirm, `POST …/document`. The document route reports memory changes but never saves them; `--sync-memories` replaces the memory table with the document's `## Memories` |
+| `npc memory list\|add\|set\|rm <npc>` | `GET/POST /npc-city/residents/:id/memories`, `PATCH/DELETE /npc-city/memories/:id` (title ≤200, date ≤40, weight 1–5, type formative\|trauma\|joy\|connection\|revelation). `list` marks the top 3 by weight (then newest) — the only ones the live reply prompt reads, content clipped to 140 |
+| `npc album list <npc> [album]` · `create <npc> --name [-d] [--photo …]` · `add <npc> <album> <photo…>` · `set <npc> <album> [--name] [-d] [--cover n] [--label n=text…]` · `rm-photo <npc> <album> <n…>` · `rm <npc> <album>` | `GET/POST /npc-city/residents/:id/albums`, `PATCH/DELETE …/albums/:albumId` (label ≤120, description ≤500; photos `{id, assetId, url, label}`, the CLI mints ids and resolves asset ids / uploads files to URLs; `<album>` = number or id) |
+| `npc readiness <npc>` | `GET /npc-city/live/residents/:id/readiness` — soul integrity, gate reasons (selfDescription / humanProtocol >10 chars, a trait, headshot, a scene), scenes, voice sample, stages |
+| `npc stage list <npc>` | `GET /npc-city/live/residents/:id/stages` |
+| `npc stage export <stageId> [--format md\|json] [-o]` | `GET /npc-city/live/stages/:id/document` |
+| `npc stage apply <stageId> <@file\|-> [--dry-run] [-y]` | `POST …/document/preview`, confirm, `POST …/document` (text only; baked fields warn) |
+| `npc stage import <npc> <@file\|-> [-y]` | `POST /npc-city/live/residents/:id/stages/import` — a Draft stage, nothing rendered, no credits |
+| `npc stage set <stageId> [--debug on\|off] [--on on\|off] [--label]` | `PATCH /npc-city/live/stages/:id {debugMode, enabled, label}` — `--on` needs a Ready stage; debug on an on-air stage asks first |
+| `npc stage rm <stageId> [-y]` | `DELETE /npc-city/live/stages/:id` |
 | `npc transfer send <npc> --to <email\|userId> [-y]` | `POST /npc-city/residents/:id/transfer` |
 | `npc transfer list` | `GET /npc-city/transfers/incoming` + `/outgoing` |
 | `npc transfer accept\|reject\|cancel <transferId>` | `POST /npc-city/transfers/:id/<action>` |
 
+Writing the character and stages well — what each field does at runtime —
+is the `npc-character` skill.
+
 Job types: concert, release, collaboration, brand, event, ad, appearance. The
 server drops jobs without a title or date and turns unknown types into `event`;
 the CLI rejects both up front.
@@ -277,11 +289,17 @@ the CLI rejects both up front.
 | --- | --- |
 | `backreel list [--all] [-k] [--page] [--limit]` | `GET /backreel/post/search/my` (`--all`: `GET /backreel/post/search`) |
 | `backreel get <postId>` | `GET /backreel/post/list/:id` |
-| `backreel create <title> [--kind showcase\|crowdfunding] [--logline] [--category] [--project-status] [--tags a,b] [-d text\|@file] [--cover assetId] [--cover-portrait] [--trailer] [--body json]` | `POST /backreel/post/create` (always a draft) |
+| `backreel create <title> [--kind showcase\|crowdfunding] [--logline] [--media assetId...] [--category] [--project-status] [--tags a,b] [-d text\|@file] [--cover assetId] [--cover-portrait] [--trailer] [--body json]` | `POST /backreel/post/create` (always a draft) |
 | `backreel set <postId> [--title] [same flags]` | `PUT /backreel/post/list/:id` with only the given fields |
 | `backreel publish\|unpublish <postId>` | `POST /backreel/post/list/:id/publish\|unpublish` (publish needs a cover, media or an episode) |
 | `backreel rm <postId> [-y]` | `DELETE /backreel/post/list/:id` |
 | `backreel creators [-k] [--role kind] [--verified] [--no-featured] [--page] [--limit ≤48]` | `GET /backreel/creator/list` — editor-picked `featured` plus a heat-ranked page (recent likes, favorites ×2); creators with no recent activity are not listed. `--role`: investor, production_company, brand, distributor, sales_agent |
+| `backreel image <file...> --slot cover\|portrait\|media\|photo [--post id] [--check]` | reads the size locally, warns on ratio / resolution, `POST /assets/v2/upload` with width/height, then `PUT {cover\|coverPortrait\|assets}` (media appends, ≤9) |
+| `backreel image-specs` | recommended size per slot (16:9 1920×1080, 9:16 1080×1920, 3:4 1536×2048, 1:1 800×800) |
+| `backreel check <postId>` | publish blockers (title, description text/img, cover\|media\|episode, crowdfunding goal ≥1) and advice (portrait, logline, credits, VOD not ready) |
+| `backreel episode list\|add\|set\|rm\|move\|tiers\|status\|play` | whole `episodes[]` read-modify-`PUT` (≤30, showcase only). A file: `POST /backreel/vod/upload-token` → signed ApplyUploadInfo / PUT / CommitUploadInfo → `POST /backreel/vod/claim` → `vodVid`; `--legacy` / `--asset` = WJI asset. `status` / `play` use `GET …/episodes/:order/play` (409 = transcoding) |
+| `backreel enquiry list\|unread\|get\|reply\|status\|grant\|download` | `/backreel/enquiry/search?box=`, `unread-count`, `list/:id` + `list/:id/messages`, `POST list/:id/messages {body, attachments}` (files via `POST /backreel/file/upload?purpose=enquiry`), `POST list/:id/status`, `POST list/:id/grant`, `GET /backreel/file/:id/download` |
+| `backreel fund show\|set\|tier\|supporter\|donations` | read-modify-`PUT` of `campaign` (crowdfunding only) and `donation` (any post); `donations` = `GET /backreel/donation/post/:id/manage` |
 | `backreel credit list <postId>` | the post's `credits[]`, numbered |
 | `backreel credit add <postId> --role [--name] [--kind cast\|crew\|creative] [--npc] [--user] [--link] [--job <type>]` | read, append, `PUT {credits}`; `--job` then appends to the NPC's `jobs` (own NPCs only, checked first) |
 | `backreel credit rm <postId> <n...> [-y]` | read, drop, `PUT {credits}` |
@@ -290,7 +308,9 @@ Project status: planning, pre_production, in_production, post_production,
 completed. `--logline` is a one-line hook (≤200 chars, HTML stripped, `""`
 clears it) shown large on the post page and **always public**, even when the
 description is gated. The post detail no longer carries playable URLs for VOD
-episodes — playback is gated per episode on the web. `-d` plain text becomes `<p>` paragraphs; HTML passes through and
+episodes — playback is gated per episode on the web. Every `backreel` call
+sends `X-App: backreel` so notifications and mail link to Backreel. The
+`backreel` skill covers the creator workflow in depth. `-d` plain text becomes `<p>` paragraphs; HTML passes through and
 is sanitized server-side. Admin routes (`/api/backreel/*`) reject `sk_` keys.
 
 ## gen
@@ -304,7 +324,7 @@ Shared flags: `-m/--model` (required), `-p/--prompt`, `-n/--n`, `-w/--workspace`
 | --- | --- | --- |
 | `gen image` | `--ref`, `--omni`, `--style-ref`, `--reference-weight`, `--stylize`, `--model-options` | `POST /ai/assets/history/image/generations` |
 | `gen video` | `-d/--duration`, `--start-image`, `--end-image`, `--ref`, `--ref-video`, `--ref-audio` | `POST /ai/assets/history/video/generations` |
-| `gen audio` | `-d/--duration`, `--ref-audio` | `POST /ai/assets/history/audio/generations` |
+| `gen audio` | `-d/--duration`, `--ref-audio`, `--ref` (one image, e.g. a headshot → a Seed Audio voice sample; not with `--ref-audio`) | `POST /ai/assets/history/audio/generations` |
 | `gen cost -t <type> -m <model>` | `-n`, `-p`, `-d`, `-r`, `--refs`, `--values` | `POST /ai/assets/preComputeCost` |
 
 Every generation goes through the history endpoint — there is no raw mode. The