@wji.ai/cli 0.6.1 → 0.7.0

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