@wji.ai/cli 0.6.1 → 0.7.1

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@wji.ai/cli",
-  "version": "0.6.1",
+  "version": "0.7.1",
   "description": "Command line interface for the WJI AI platform",
   "license": "UNLICENSED",
   "author": "WJI AI",
   "homepage": "https://wji.ai",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/ultra-instinct-ai/wji-cli.git"
+    "url": "git+https://github.com/ultra-instinct-ai/wji-cli.git",
+    "directory": "packages/cli"
   },
   "keywords": [
     "wji",
@@ -30,19 +31,15 @@
     "node": ">=20"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json && chmod +x dist/index.js",
-    "dev": "tsc -p tsconfig.json --watch",
+    "build": "tsup && chmod +x dist/index.js",
+    "dev": "tsup --watch",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "start": "node dist/index.js",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "pnpm run build"
   },
   "dependencies": {
     "commander": "^12.1.0"
   },
-  "devDependencies": {
-    "@types/node": "^22.10.0",
-    "typescript": "^5.7.2"
-  },
   "publishConfig": {
     "access": "public"
   }

package/skill/backreel/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: backreel
+description: Run a creator's works on Backreel (the film / short-drama showcase and crowdfunding site that shares accounts with WJI) with the `wji` CLI — create and publish a post (作品), prepare and upload cover / portrait / LookBook images at the right size and ratio, add cast and crew credits, upload and maintain episode videos (分集 via BytePlus VOD), set who can watch each episode, run a crowdfunding campaign with donation tiers and offline supporters, read donation records, and answer enquiries (查詢 / 合作邀請 / 投資 / 授權) — reply, accept or decline, grant partner access. Use whenever a task mentions Backreel, a Backreel post / work / reel, its episodes, trailer, cover or poster sizes, crowdfunding / 眾籌 / 捐款, supporters, or enquiries / 查詢 on a creator's work.
+---
+
+# Backreel
+
+Backreel shares accounts and the API with WJI, so this skill sits on the `wji`
+skill — read that one for sign-in (`wji auth whoami`), profiles and asset
+basics. Everything here is `wji backreel …` (alias `wji br …`). Every command
+takes `--json`; use it when you need ids.
+
+Only the **post's creator** can edit, publish, upload episodes or see
+enquiries and donations for it — admins included, the post routes refuse
+anyone else. Check who you are before touching someone's work:
+
+```bash
+wji auth whoami
+wji br list                     # your posts, drafts included
+```
+
+## How a Backreel post is built
+
+| Part | What it is | Command |
+| --- | --- | --- |
+| kind | `showcase` (episodes, trailer) or `crowdfunding` (goal, supporters) — switching wipes the other side's data | `br create --kind`, `br set --kind` |
+| title / logline / description | logline = one public line ≤200 chars; description = HTML or plain text | `br set --logline`, `-d @file.md` |
+| images | 16:9 cover, 9:16 portrait, LookBook gallery (≤9), credit photos | `br image <file> --slot … --post` |
+| trailer | a video asset ≤30 s | `wji asset upload` → `br set --trailer` |
+| episodes | ≤30, each with its own viewer tier, hosted on VOD | `br episode …` |
+| credits | cast / crew / creative, ≤30, may link a WJI user or an NPC | `br credit …` |
+| campaign + donations | goal, offline total, deadline, donation tiers, offline supporters | `br fund …` |
+| enquiries | messages from people who want to work with / invest in / license the work | `br enquiry …` |
+
+Viewer tiers, lowest to highest: `public` (anyone) < `member` (signed in) <
+`supporter` (has donated) < `partner` (granted by the creator or a verified
+investor / company). The logline and the cards are always public.
+
+## 1. Create a post and get it publishable
+
+```bash
+wji br create "港口" --kind showcase --logline "一個漁村少年的最後一夏" \
+  -d @synopsis.md --category short_drama --project-status in_production --tags drama,hk
+wji br check <postId>           # blockers (✗) and advice (!)
+```
+
+`create` always makes a **draft**. Publishing needs a title, a description
+with text or an image, and at least one of cover / LookBook media / an
+episode; a crowdfunding post also needs a goal ≥ 1. `br check` lists exactly
+what is missing — run it before `br publish <postId>`. `br unpublish` takes a
+post offline (it can be republished); `br rm` deletes it.
+
+Categories the web offers: `narrative_short`, `movie`, `short_drama`,
+`web_movie`, `tv_commercial`, `mv`, `animation`, `creative`, `tutorial`,
+`other`.
+
+## 2. Images — size and ratio
+
+The server accepts any image and **crops to fill** every frame, so a wrong
+ratio silently loses the edges. Prepare each slot at its own ratio:
+
+| Slot | Ratio | Ideal | Minimum | Where |
+| --- | --- | --- | --- | --- |
+| `cover` | 16:9 | 1920×1080 | 1280×720 | page header, shares; also cropped to 4:3 on cards and ~16:7 in reel strips |
+| `portrait` | 9:16 | 1080×1920 | 720×1280 | mobile hero / poster (falls back to a crop of the cover) |
+| `media` | 3:4 | 1536×2048 | 900×1200 | LookBook tiles (≤9 items, images or videos) |
+| `photo` | 1:1 | 800×800 | 400×400 | credit photo, supporter avatar (shown round) |
+
+JPEG / PNG / WebP, ≤25 MB. Long edges over 3840 px are downsized and files
+over 10 MB are re-encoded as JPEG on upload.
+
+```bash
+wji br image-specs                                   # the table above
+wji br image cover.jpg --slot cover --check          # measure only
+wji br image cover.jpg --slot cover --post <postId>  # check, upload, set
+wji br image poster.png --slot portrait --post <postId>
+wji br image s1.jpg s2.jpg s3.jpg --slot media --post <postId>   # appends to the LookBook
+wji br set <postId> --media <assetId…>               # replace / reorder the LookBook ("none" clears)
+```
+
+`br image` reads the size from the file, warns about a wrong ratio or a soft
+(too small) image, and refuses files it cannot upload. Treat a warning as a
+reason to re-crop, not to ignore. Read [reference/images.md](reference/images.md)
+for composition rules (safe area for the 4:3 and 16:7 crops), making the
+9:16 poster from the cover with AI, and credit photos.
+
+## 3. Episodes and videos
+
+```bash
+wji br episode add <postId> E01.mp4 -t "第一集 重逢"            # uploads to VOD, claims it, appends
+wji br episode add <postId> E00.mp4 -t "前導" --at 1 --tier public
+wji br episode list <postId>
+wji br episode status <postId>        # transcoding: processing → ready (refreshes from VOD)
+wji br episode tiers <postId> --public-to 2 --member-to 5 --rest supporter
+wji br episode set <postId> 3 -t "第三集（導演版）"      # rename
+wji br episode set <postId> 3 E03_v2.mp4               # replace the video
+wji br episode move <postId> 4 2
+wji br episode rm <postId> 6 -y
+wji br episode play <postId> 1        # short-lived URL to watch it yourself
+```
+
+Episodes exist on **showcase** posts only (≤30). A local file goes straight
+to Backreel's BytePlus VOD space, which serves short-lived signed URLs —
+nothing on the page can be copied and shared. Transcoding takes a few minutes;
+an episode stays `processing` until then and viewers get "still
+transcoding". Numbers on the command line are 1-based positions. Read
+[reference/episodes.md](reference/episodes.md) for the trailer, the legacy
+asset path, tier strategy and failure handling.
+
+## 4. Crowdfunding and donations
+
+```bash
+wji br create "下一部長片" --kind crowdfunding -d @pitch.md
+wji br fund set <postId> --goal 500000 --deadline 2026-12-31 \
+  --donations on --currency hkd --min 50
+wji br fund tier add <postId> --title "早鳥" --amount 200 --perks "片尾鳴謝" --limit 300
+wji br fund supporter add <postId> --name "ABC Films" --amount 50000
+wji br fund set <postId> --offline-raised 50000      # money raised outside Backreel
+wji br fund show <postId>                            # progress, settings, tiers
+wji br fund donations <postId>                       # online donations, balance, payouts
+```
+
+Progress = offline total + online donations. Donations (Stripe) work on any
+published post, not just crowdfunding, and stop at the deadline; the currency
+locks after the first donation. Payouts and refunds are done by Backreel
+staff, not the CLI. Read [reference/crowdfunding.md](reference/crowdfunding.md)
+for tier design and what supporters unlock.
+
+## 5. Enquiries
+
+```bash
+wji br enquiry unread
+wji br enquiry list                         # inbox, newest activity first (● = unread)
+wji br enquiry list --type investment --status new
+wji br enquiry get <enquiryId>              # full request + thread; marks it read
+wji br enquiry download <fileId>            # an attachment (private file)
+wji br enquiry reply <enquiryId> "多謝來信…" -a deck.pdf
+wji br enquiry status <enquiryId> in_discussion    # | accepted | declined | archived
+wji br enquiry grant <enquiryId>            # give the sender partner access
+```
+
+Types: collaboration, new_project, investment, licensing, access_request,
+general. Accepting an **access_request** grants partner access automatically;
+`grant` does it from any enquiry (creator only) and marks it accepted. Every
+reply notifies the sender in-app and by email (at most every 30 min), so
+**show the user the reply text and get their OK before sending**, and never
+accept, decline or grant on your own judgement. Read
+[reference/enquiries.md](reference/enquiries.md) for triage and reply
+patterns.
+
+## Credits
+
+```bash
+wji br credit add <postId> --kind creative --name "陳導" --role 導演 --photo <assetId>
+wji br credit add <postId> --kind cast --npc @mika --role "飾 阿明"
+wji br credit add <postId> --kind crew --user <userId> --role 攝影指導   # their name and avatar win
+wji br credit list <postId>
+wji br credit rm <postId> 3 -y
+```
+
+## Rules of thumb
+
+- **Ask before anything outward-facing**: publishing, unpublishing, deleting,
+  replying to or deciding an enquiry, granting access, turning donations on.
+  Draft edits are safe to make and show.
+- Generating images (e.g. the AI poster) spends WJI credits — confirm first.
+- Episode uploads go to the live VOD space even from a test post; don't
+  upload throwaway clips.
+- Re-run `br check` after big edits; run `br episode status` after uploads.
+- Errors come back in Chinese from the server (e.g. `分集最多 30 集`); relay
+  them as they are and say what to change.

package/skill/backreel/reference/crowdfunding.md

@@ -0,0 +1,82 @@
+# Crowdfunding, donations and supporters
+
+## Two pieces that work together
+
+| | Campaign | Donations |
+| --- | --- | --- |
+| on | crowdfunding posts only | any published post |
+| holds | goal, offline total, deadline, offline supporter list | on/off, currency, minimum, tiers |
+| set with | `br fund set --goal --offline-raised --deadline`, `br fund supporter …` | `br fund set --donations --currency --min`, `br fund tier …` |
+
+The public progress bar = `--offline-raised` + online donations; the
+supporter count = offline supporters + online donors.
+
+## Setting up a campaign
+
+```bash
+wji br create "下一部長片" --kind crowdfunding -d @pitch.md --logline "…"
+wji br fund set <postId> --goal 500000 --deadline 2026-12-31
+wji br fund set <postId> --donations on --currency hkd --min 50
+wji br fund tier add <postId> --title "早鳥支持" --amount 200 --perks "片尾鳴謝 + 數碼海報" --limit 300
+wji br fund tier add <postId> --title "製片人" --amount 20000 --perks "聯合製片人名銜、探班一次" --limit 5
+wji br check <postId>
+wji br publish <postId>          # ask first
+```
+
+- A crowdfunding post cannot publish with a goal below 1.
+- Currencies: hkd, usd, twd, sgd, eur, gbp. **Locked after the first
+  donation** — choose before publishing.
+- Amounts are whole numbers. Every tier must be ≥ the minimum (and ≥ 1);
+  ≤10 tiers; `--limit` caps the slots (`--limit 0` on `tier set` = unlimited).
+- The deadline stops donations at that moment; `--deadline none` removes it.
+- A single donation is capped at 100,000.
+
+## Designing tiers
+
+- 3–5 tiers read best: an entry tier most people can afford, a "real
+  supporter" tier, one or two premium tiers with scarce perks (`--limit`).
+- Perks should be concrete and deliverable: credit wording, a screening,
+  a set visit, early access. Supporter **episodes** are a perk too — tiers
+  set to `supporter` unlock for anyone who has donated (see
+  [episodes.md](episodes.md)).
+- Changing a tier's amount does not affect past donations; they keep a
+  snapshot of the tier they bought.
+
+## Offline supporters
+
+People who paid by bank transfer, sponsorship etc. Add them so the wall and
+count reflect reality, and raise the offline total separately:
+
+```bash
+wji br fund supporter add <postId> --name "ABC Films" --amount 50000 --avatar <assetId>
+wji br fund set <postId> --offline-raised 50000
+wji br fund supporter list <postId>
+wji br fund supporter rm <postId> 2 -y
+```
+
+Adding a supporter does **not** change the raised amount — update
+`--offline-raised` yourself (keep the two consistent). Avatars are square
+images (`br image logo.png --slot photo`).
+
+## Donation records
+
+```bash
+wji br fund donations <postId>
+```
+
+Shows raised / paid out / balance, then each donation: time, donor (anonymous
+donors stay hidden even from the creator), amount, tier, status (`paid`,
+`partially_refunded`, `refunded`, `failed`, `cancelled`; a red *disputed*
+marks a card chargeback) and the donor's message. Payouts and
+refunds are handled by Backreel staff — the creator asks them, the CLI cannot
+do it.
+
+## Showcase posts can take donations too
+
+A showcase post (episodes) can turn donations on to sell `supporter` access
+to later episodes — there is just no goal or progress bar:
+
+```bash
+wji br fund set <postId> --donations on --currency hkd --min 30
+wji br episode tiers <postId> --public-to 2 --rest supporter
+```

package/skill/backreel/reference/enquiries.md

@@ -0,0 +1,80 @@
+# Enquiries
+
+Anyone signed in can send an enquiry about a **published** post — to its
+creator, or (for collaboration / new_project / general) to a credited person
+with a linked account. The creator reads and answers them here.
+
+## Types and what they carry
+
+| type | meaning | extra fields shown by `enquiry get` |
+| --- | --- | --- |
+| `collaboration` | work together on something | — |
+| `new_project` | an offer to hire for a project | project type, title, budget range + currency, timeline, location, role needed |
+| `investment` | wants to invest | ticket size + currency |
+| `licensing` | wants to license the work | territory, media, term |
+| `access_request` | wants partner access to gated material | access purpose; `sender access` shows their current tier |
+| `general` | anything else | — |
+
+Every enquiry has the sender's contact block (name, email, phone, company),
+their verification badges (✓investor, ✓production_company …) and up to 5
+private attachments (`enquiry download <fileId>` — the link lasts 60 s).
+
+## Status flow
+
+```
+new ──reply──▶ in_discussion ──▶ accepted | declined | archived
+   (sender may withdraw while new / in_discussion; nothing moves after withdrawn)
+```
+
+- The recipient (you) sets `in_discussion`, `accepted`, `declined`,
+  `archived`. Replying to a `new` enquiry moves it to `in_discussion`.
+- `archived` hides it from the inbox (`enquiry list --archived` shows it); a
+  reply from the sender brings it back.
+- `accepted` on an **access_request** grants partner access immediately.
+- `enquiry grant <id>` grants partner access from any enquiry you received as
+  the creator, and marks an open one accepted. It is offered only while the
+  sender has no partner access (`can` line of `enquiry get`).
+- Accept / decline notify the sender in-app and by email.
+
+## Triage routine
+
+```bash
+wji br enquiry unread
+wji br enquiry list --unread
+wji br enquiry get <id>          # read everything, including attachments
+```
+
+Summarise each for the user: who (name, company, verification), what they
+want, the money / dates involved, and what the creator would need to decide.
+Do **not** decide for them — accepting, declining and granting access are the
+creator's calls.
+
+## Replying
+
+Replies are ≤4000 characters, go to the other side in-app immediately and by
+email at most every 30 minutes. Draft the reply, show it, send only after the
+user agrees:
+
+```bash
+wji br enquiry reply <id> @reply.md -a pitch-deck.pdf
+```
+
+Attachments: documents (PDF, DOCX, XLSX, PPTX, CSV) and images, ≤20 MB each,
+≤5 per message.
+
+Patterns that work:
+
+- **Acknowledge + next step**: thank them, restate what they asked in one
+  line, say what happens next and when ("I'll send the budget breakdown by
+  Friday").
+- **Need more**: ask the 2–3 specific questions you need (budget, schedule,
+  rights territory) instead of a vague "tell me more".
+- **Decline kindly**: one line of thanks, one line of reason if the user wants
+  to give one, leave the door open — then `enquiry status <id> declined`.
+- Match the sender's language (Cantonese / Mandarin / English).
+
+## Limits worth knowing
+
+Senders can have one open enquiry of the same type per post, 3 per post per
+day and 20 per day overall — repeated spam beyond that is blocked by the
+server. Blocking and reporting a sender are done on the web.

package/skill/backreel/reference/episodes.md

@@ -0,0 +1,104 @@
+# Episodes, trailer and video upkeep
+
+## Two kinds of video on a post
+
+| | Trailer | Episodes |
+| --- | --- | --- |
+| posts | any | **showcase only** (switching to crowdfunding drops them) |
+| count | one | ≤30 |
+| length | ≤30 s (server allows +1 s) | no limit |
+| storage | WJI asset (public URL) | BytePlus VOD (signed URL per play, ~5 min) |
+| gated | no — always public | per episode: public / member / supporter / partner |
+
+### Trailer
+
+```bash
+wji asset upload trailer.mp4 --json           # ≤200 MB; duration is probed
+wji br set <postId> --trailer <assetId>
+```
+
+The server rejects a trailer over 31 s when it knows the duration. Cut it to
+≤30 s first.
+
+## Uploading episodes
+
+```bash
+wji br episode add <postId> E01.mp4 -t "第一集"
+```
+
+What happens: the CLI asks Backreel for a 15-minute upload credential scoped
+to its VOD space, uploads the file directly to BytePlus, **claims** it (the
+server checks the space, tags it with the post, publishes it and starts
+transcoding), then saves the episode list with the new `vodVid`.
+
+- Formats: `.mp4`, `.mov`, `.m4v`, `.webm`. Upload the finished master;
+  VOD transcodes to MP4 for playback.
+- The whole file goes up in one request — fine for episodes (hundreds of MB).
+  Multi-GB masters are better uploaded from the web, which chunks them.
+- A credential lasts 15 minutes and the server allows 30 per 10 minutes —
+  upload a season one episode at a time, not in parallel.
+- `--vid <vid>` attaches a video already in the space (e.g. uploaded on the
+  web) without re-uploading.
+
+### Legacy path
+
+`--legacy` (or `--asset <assetId>`) stores the episode as a plain WJI asset
+(≤200 MB) with a permanent public URL. It plays immediately with no
+transcoding, but anyone who sees the URL can share it, and tier locks only hide
+it on the page. Use VOD for anything gated; legacy only for short public
+extras.
+
+## Transcoding status
+
+```bash
+wji br episode status <postId>
+```
+
+VOD status only updates when someone asks to play, so `status` asks for each
+VOD episode as the owner and reports `processing`, `ready` or `failed`.
+A few minutes per episode is normal. Viewers who press play before it is ready
+see "這一集還在轉碼中". `failed` → upload the file again:
+`wji br episode set <postId> <n> E0n_fixed.mp4`.
+
+Publishing does **not** wait for transcoding — check `status` (or `br check`)
+before announcing a release.
+
+## Order and numbering
+
+Positions on the command line are 1-based (`episode set <post> 3`). The
+server re-numbers after every change, so after `move` / `rm` re-read
+`episode list` before the next positional command.
+
+```bash
+wji br episode move <postId> 5 2      # episode 5 becomes episode 2
+wji br episode add <postId> SP.mp4 -t "特別篇" --at 4
+wji br episode rm <postId> 7 8 -y
+```
+
+Removing an episode does not delete the video from VOD; re-adding it later
+with `--vid` works.
+
+## Who can watch: tiers
+
+`public` anyone · `member` signed in · `supporter` has donated to this post ·
+`partner` granted by the creator (or an auto-partner verified company).
+
+Common ladders:
+
+```bash
+# Free pilot, members for the first act, supporters for the rest
+wji br episode tiers <postId> --public-to 1 --member-to 3 --rest supporter
+# Everything public except a partner-only director's cut at the end
+wji br episode tiers <postId> --public-to 11 --rest partner
+```
+
+`supporter` only works if people can donate — turn donations on
+(`br fund set --donations on`) or nobody can reach those episodes. Locked
+episodes still show their title and a lock, and never expose a URL.
+
+## Owner checks
+
+```bash
+wji br episode play <postId> 1     # signed URL, ~5 minutes; watch it yourself
+wji br check <postId>              # flags episodes not ready on VOD
+```

package/skill/backreel/reference/images.md

@@ -0,0 +1,76 @@
+# Backreel images
+
+## Where each image shows, and how it is cropped
+
+Every image frame on Backreel uses *cover* fitting: the image fills the frame
+and whatever sticks out is cut. Nothing is letterboxed, and the server does not
+check ratios — so the only protection is preparing each slot at its own ratio.
+
+| Slot | Field | Prepared as | Also shown as | Keep inside |
+| --- | --- | --- | --- | --- |
+| cover | `cover` | 16:9, 1920×1080 | 4:3 list cards, ~16:7 reel strips, share previews | the centre 4:3 *and* the middle 16:7 band — faces and title text in the centre, nothing important near the top or bottom 20% or the left/right 12% |
+| portrait | `coverPortrait` | 9:16, 1080×1920 | mobile hero, poster tiles | the middle 80% vertically; leave the bottom third calm if the page overlays the title there |
+| media | `assets[]` (LookBook) | 3:4, 1536×2048 | 3:4 tiles; opens full size | subject centred; stills shot 16:9 lose their sides — re-crop to 3:4 rather than upload as is |
+| photo | credit `photo`, supporter `avatar` | 1:1, 800×800 | a circle | the face centred, head and shoulders, no text |
+
+`--slot` names: `cover`, `portrait`, `media`, `photo`.
+
+There is no separate "card" image on the live site yet: cards crop the 16:9
+cover to 4:3, which is why the cover's centre matters. (A dedicated 4:3
+`cardCover` field exists on an unreleased backend branch; once it ships it
+will be its own slot.)
+
+## Limits applied on upload (`/assets/v2/upload`)
+
+- ≤25 MB per image; JPEG, PNG, WebP (AVIF and GIF are accepted too).
+- Long edge over 3840 px → downsized to 3840.
+- Over 10 MB → re-encoded as JPEG quality 95. Prefer a high-quality JPEG
+  around 1–4 MB; a 30 MB PNG gains nothing.
+- A ~512 px thumbnail is generated automatically.
+- EXIF rotation is not applied by `br image`'s size check — export images
+  already upright.
+
+## Checking and fixing
+
+```bash
+wji br image still.jpg --slot media --check
+```
+
+- `! ratio … is not 3:4 — the edges will be cropped` → re-crop to the slot
+  ratio. On macOS without an editor:
+  `sips --cropToHeightWidth 2048 1536 in.jpg --out out.jpg` (crops around the
+  centre; resize first with `sips -Z 2048` if needed).
+- `! … below 1280×720; it will look soft` → find a larger source; upscaling a
+  small frame does not add detail.
+- `✗ not a PNG, JPEG, WebP or GIF image` → convert first
+  (`sips -s format jpeg in.heic --out out.jpg`).
+
+## The 9:16 poster from the 16:9 cover (AI)
+
+When there is no portrait artwork, the web offers "make portrait with AI": it
+re-composes the cover into 9:16 with an image model. The same with the CLI —
+**this spends WJI credits, so confirm with the user first**:
+
+```bash
+wji br get <postId> --json | jq -r .cover.id          # the cover asset id
+wji gen image -m gpt-image-2.5-flare-fal -r 9:16 --ref <coverAssetId> \
+  -p "Recompose this film key art as a 9:16 vertical poster. Keep the same characters, faces, wardrobe, colour grade and mood; extend the scene vertically; no text, no logos." \
+  --model-options '{"quality":"high","resolution":"1080p"}' --wait --json
+wji br set <postId> --cover-portrait <newAssetId>
+```
+
+Look at the result before setting it — faces drift. Generate again with a
+more specific prompt rather than accepting a changed face.
+
+## Inline images in the description
+
+The description is sanitized HTML; `<img src="https://…">` survives (http/https
+only), so an uploaded asset's URL can be embedded:
+
+```bash
+wji asset upload still.jpg --json | jq -r .url
+wji br set <postId> -d @description.html
+```
+
+A description that is only an image still counts as "has a description" for
+publishing.

package/skill/npc-character/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: npc-character
+description: Write a virtual character for NPC City that feels like a real person — persona, soul (drive, traits, values, fears, contradiction), background and memories, voice and speaking tone, protocols for talking to viewers, on-camera habits — and the live stages she performs on (occasion, greeting, idle loops, reply direction), then apply them with the `wji` CLI (`wji npc doc`, `wji npc memory`, `wji npc stage`). Use whenever someone wants to create, deepen, fix or review an NPC / virtual idol / AI character / VTuber / 虛擬角色 / 人設 / 角色設定 / soul / persona / background story on NPC City, write or improve its live stream stage, or asks why their NPC sounds generic.
+---
+
+# NPC City characters
+
+NPC City residents ("NPCs") are virtual characters who live-stream: a viewer
+types, a reply model writes what she **says** and **does**, and a video model
+performs it. Everything in this skill is about making that character feel
+like a specific person instead of a list of adjectives — and about putting
+the words where the runtime actually reads them.
+
+Sits on the `wji` skill (sign-in, profiles). Commands are `wji npc …`; your
+NPC is addressed by id, `@handle` or name.
+
+## The workflow
+
+1. **Read what exists** — never start from a blank page if the NPC exists.
+   For a **new** NPC, create the shell first (needs NPC City spawn
+   permission; it starts private), then upload the headshot and at least one
+   scene image on the web — live stages need both:
+   ```bash
+   wji npc handle nagi.npc                                  # is the handle free?
+   wji npc create "NAGI" --role "Radio Host" --genre "Lo-fi" --handle nagi.npc
+   ```
+   The handle is fixed from here on; the name is stored in capitals.
+   Visual assets (headshot 1:1, **Character Sheet 16:9** with front / back /
+   side views, outfit flat lays 3:4, scenes 16:9) have fixed formats — see
+   [reference/visual-kit.md](reference/visual-kit.md) before generating any.
+   ```bash
+   wji npc list
+   wji npc doc export @yuzu.npc -o yuzu.md      # profile + soul as one Markdown file
+   wji npc memory list @yuzu.npc
+   wji npc readiness @yuzu.npc                  # integrity %, what blocks going live
+   ```
+2. **Interview, then decide** — ask the creator the five questions in
+   [reference/interview.md](reference/interview.md), or make bold choices
+   and say which ones you made. Lock the **want, the need and the one
+   contradiction** before writing any field.
+3. **Write the character document** with the method in
+   [reference/character-craft.md](reference/character-craft.md), in the
+   grammar of [reference/document-format.md](reference/document-format.md).
+   Spend the words where [reference/runtime.md](reference/runtime.md) says
+   the model reads them.
+4. **Write the voice** — speaking tone, sample lines that fit one live reply
+   (40 English words / 60 CJK characters), code-switching, on-camera habits in
+   English: [reference/voice.md](reference/voice.md).
+5. **Review** with the checklist at the end of character-craft.md, then show
+   the creator a diff before writing anything:
+   ```bash
+   wji npc doc apply @yuzu.npc @yuzu.md --dry-run
+   wji npc doc apply @yuzu.npc @yuzu.md --sync-memories      # asks before applying
+   ```
+   `--sync-memories` matters: the document route silently ignores the
+   `## Memories` section; this flag replaces the NPC's memories with it.
+6. **Her public life** — a work timeline (`wji npc job`) and photo albums
+   (`wji npc album`) that tell the same story as her key events and
+   memories: [reference/life.md](reference/life.md).
+7. **Stage** — once the character is right, write a live stage document with
+   [reference/stage-craft.md](reference/stage-craft.md) and import it as a
+   free draft:
+   ```bash
+   wji npc stage list @yuzu.npc
+   wji npc stage import @yuzu.npc @yuzu.stage.md       # Draft — nothing rendered, no credits
+   wji npc stage export <stageId> -o stage.md
+   wji npc stage apply <stageId> @stage.md --dry-run
+   ```
+8. **Rehearse** — on a Ready stage, `wji npc stage set <stageId> --debug on`
+   makes live replies come back as text plus a full prompt trace and no
+   video (no credits for renders). Chat with her on the web, read the
+   TRACE panel, fix the document, repeat. Turn it off afterwards
+   (`--debug off`); never leave an on-air stage in debug mode.
+
+Two complete characters with a stage each, both importing cleanly — use them
+as the bar, not as templates to copy:
+[YUZU](examples/yuzu.character.md) / [stage](examples/yuzu.stage.md) — a
+Cantonese singer in her family's closing dessert shop;
+[NAGI](examples/nagi.character.md) / [stage](examples/nagi.stage.md) — a
+Japanese late-night radio host who reads listener letters from a closet.
+
+## What the runtime reads (short version)
+
+| Matters a lot | Matters | Display only (never reaches a model) |
+| --- | --- | --- |
+| selfDescription (first 400 chars) · speaking tone (500) · human protocol (500) · top 3 memories by weight (140 chars each) · traits · on-camera action (300, English) · languages tag | name · role · pronouns · primary drive · values · fears · origin (300) · first 8 key events · current focus & goals · trigger keywords · avoid topics · speech pattern · axes ≤30 or ≥70 · aesthetic keywords · visual style | tagline · genre · bio (unless selfDescription is empty) · creation story · NPC protocol · data source notes · activity level · post frequency · jobs · relationships · socials · colour |
+
+Write display-only fields for the profile page and for consistency, but put
+the character's *behaviour* into the left columns. Details and the exact
+prompt order: [reference/runtime.md](reference/runtime.md).
+
+## Hard rules
+
+- **Real people**: never build an NPC that imitates a real, identifiable
+  person (name, face, voice, life story) unless the creator says they hold
+  the rights — then tag it `presenceKind=licensed-presence` (or
+  `legacy-return` for an estate-approved return). Inspired-by is fine;
+  impersonation is not.
+- **Adults only** for anything romantic or flirtatious, and say so through
+  the story (age-feel in origin and memories), not a number in the bio.
+  Never write a character who is, or reads as, a minor in a romantic or
+  sexual frame. NSFW rating does not change this.
+- **Avoid topics are hard limits** the reply model deflects in character —
+  add politics and real-celebrity gossip unless the creator wants otherwise.
+- **Nothing breaks the fourth wall**: no "as an AI", no "my prompt", no
+  "language model" anywhere in the document.
+- **Ask before** applying a document, syncing memories, importing or
+  deleting a stage, and turning a stage on air or into debug mode. Rendering
+  keyframes and clips costs credits and is done on the web, with the
+  creator's go-ahead.
+- Do not change the `@handle` — it is fixed; a document cannot change it.