@wji.ai/cli 0.6.1 → 0.7.0

package/dist/core/image.js

@@ -0,0 +1,106 @@
+import { open, stat } from 'node:fs/promises';
+/** Read width × height from a PNG, JPEG, WebP or GIF header — no image library. */
+export async function imageSize(file) {
+    const fh = await open(file, 'r');
+    try {
+        const size = (await fh.stat()).size;
+        const head = Buffer.alloc(Math.min(size, 64 * 1024));
+        await fh.read(head, 0, head.length, 0);
+        return parseImageSize(head);
+    }
+    finally {
+        await fh.close();
+    }
+}
+export function parseImageSize(b) {
+    // PNG: signature + IHDR
+    if (b.length >= 24 && b.readUInt32BE(0) === 0x89504e47) {
+        return { width: b.readUInt32BE(16), height: b.readUInt32BE(20), format: 'png' };
+    }
+    // GIF
+    if (b.length >= 10 && b.toString('ascii', 0, 3) === 'GIF') {
+        return { width: b.readUInt16LE(6), height: b.readUInt16LE(8), format: 'gif' };
+    }
+    // WebP
+    if (b.length >= 30 && b.toString('ascii', 0, 4) === 'RIFF' && b.toString('ascii', 8, 12) === 'WEBP') {
+        const chunk = b.toString('ascii', 12, 16);
+        if (chunk === 'VP8X')
+            return { width: 1 + b.readUIntLE(24, 3), height: 1 + b.readUIntLE(27, 3), format: 'webp' };
+        if (chunk === 'VP8 ')
+            return { width: b.readUInt16LE(26) & 0x3fff, height: b.readUInt16LE(28) & 0x3fff, format: 'webp' };
+        if (chunk === 'VP8L') {
+            const bits = b.readUInt32LE(21);
+            return { width: (bits & 0x3fff) + 1, height: ((bits >> 14) & 0x3fff) + 1, format: 'webp' };
+        }
+    }
+    // JPEG: walk segments to the first SOFn
+    if (b.length >= 4 && b[0] === 0xff && b[1] === 0xd8) {
+        let i = 2;
+        while (i + 9 < b.length) {
+            if (b[i] !== 0xff) {
+                i++;
+                continue;
+            }
+            const marker = b[i + 1];
+            if (marker === 0xd8 || marker === 0x01 || (marker >= 0xd0 && marker <= 0xd7)) {
+                i += 2;
+                continue;
+            }
+            const len = b.readUInt16BE(i + 2);
+            const isSof = marker >= 0xc0 && marker <= 0xcf && ![0xc4, 0xc8, 0xcc].includes(marker);
+            if (isSof) {
+                const height = b.readUInt16BE(i + 5);
+                const width = b.readUInt16BE(i + 7);
+                // EXIF orientation is not applied — the server does not rotate either.
+                return { width, height, format: 'jpeg' };
+            }
+            i += 2 + len;
+        }
+    }
+    return null;
+}
+/**
+ * Backreel image slots. The backend enforces no ratio or resolution — every
+ * slot is shown with `object-cover`, so a wrong ratio is silently cropped.
+ * These are the sizes that fill each frame sharply; `min` is the floor below
+ * which the image looks soft on a desktop screen.
+ */
+export const IMAGE_SLOTS = {
+    cover: { ratio: 16 / 9, label: '16:9', ideal: '1920×1080', min: [1280, 720], note: 'also cropped to 4:3 on cards and ~16:7 in reel strips — keep the subject centred' },
+    portrait: { ratio: 9 / 16, label: '9:16', ideal: '1080×1920', min: [720, 1280], note: 'mobile hero / poster; falls back to a crop of the cover when missing' },
+    media: { ratio: 3 / 4, label: '3:4', ideal: '1536×2048', min: [900, 1200], note: 'LookBook tiles are cropped to 3:4' },
+    photo: { ratio: 1, label: '1:1', ideal: '800×800', min: [400, 400], note: 'credit photo / supporter avatar, shown in a circle' },
+};
+/** Server limits from /assets/v2/upload and normalizeImageForStorage. */
+export const IMAGE_MAX_BYTES = 25 * 1024 * 1024;
+export const IMAGE_MAX_LONG_EDGE = 3840;
+const RATIO_TOLERANCE = 0.03;
+export async function checkImage(file, slot) {
+    const spec = IMAGE_SLOTS[slot];
+    const bytes = (await stat(file)).size;
+    const dims = await imageSize(file);
+    const errors = [];
+    const warnings = [];
+    if (bytes > IMAGE_MAX_BYTES)
+        errors.push(`file is ${(bytes / 1048576).toFixed(1)} MB; the upload limit is 25 MB`);
+    if (!dims) {
+        errors.push('not a PNG, JPEG, WebP or GIF image (or the header could not be read)');
+        return { file, slot, bytes, dims, errors, warnings, spec };
+    }
+    const ratio = dims.width / dims.height;
+    if (Math.abs(ratio - spec.ratio) / spec.ratio > RATIO_TOLERANCE) {
+        warnings.push(`ratio ${dims.width}:${dims.height} ≈ ${ratio.toFixed(2)} is not ${spec.label} — the edges will be cropped`);
+    }
+    const [minW, minH] = spec.min;
+    const shortSide = spec.ratio >= 1 ? dims.height : dims.width;
+    const minShort = spec.ratio >= 1 ? minH : minW;
+    if (shortSide < minShort) {
+        warnings.push(`${dims.width}×${dims.height} is below ${minW}×${minH}; it will look soft (ideal ${spec.ideal})`);
+    }
+    if (Math.max(dims.width, dims.height) > IMAGE_MAX_LONG_EDGE) {
+        warnings.push(`long edge over ${IMAGE_MAX_LONG_EDGE}px — the server downsizes it on upload`);
+    }
+    if (bytes > 10 * 1024 * 1024)
+        warnings.push('over 10 MB — the server re-encodes it as JPEG');
+    return { file, slot, bytes, dims, errors, warnings, spec };
+}

package/dist/core/npc.js

@@ -70,7 +70,7 @@ export function parseJob(opts, base) {
     const job = {
         type: opts.type ?? base?.type ?? '',
         title: opts.title ?? base?.title ?? '',
-        detail: opts.detail ?? base?.detail ?? '',
+        detail: opts.about ?? opts.detail ?? base?.detail ?? '',
         date: opts.date ?? base?.date ?? '',
     };
     const location = opts.location ?? base?.location;

package/dist/core/vod.js

@@ -0,0 +1,149 @@
+import { createHash, createHmac } from 'node:crypto';
+import { readFile, stat } from 'node:fs/promises';
+import { extname } from 'node:path';
+const VERSION = '2023-01-01';
+const SERVICE = 'vod';
+const DEFAULT_HOST = 'vod.byteplusapi.com';
+const DEFAULT_REGION = 'ap-southeast-1';
+/** Same escaping as the volcengine signer (RFC 3986, `*` escaped too). */
+function uriEscape(value) {
+    return encodeURIComponent(value)
+        .replace(/[^A-Za-z0-9_.~\-%]+/g, escape)
+        .replace(/[*]/g, (ch) => `%${ch.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+export function canonicalQuery(params) {
+    return Object.keys(params)
+        .filter((key) => params[key] !== undefined && params[key] !== null)
+        .sort()
+        .map((key) => `${uriEscape(key)}=${uriEscape(String(params[key]))}`)
+        .join('&');
+}
+const sha256Hex = (data) => createHash('sha256').update(data).digest('hex');
+const hmac = (key, data) => createHmac('sha256', key).update(data).digest();
+/**
+ * BytePlus / volcengine request signature ("HMAC-SHA256", scope
+ * `<date>/<region>/<service>/request`). Unsigned headers: authorization,
+ * content-type, content-length, user-agent — so only X-Date,
+ * X-Security-Token and X-Content-Sha256 are signed. Exported so the test can
+ * compare it with the official signer byte for byte.
+ */
+export function signVodRequest(opts) {
+    const datetime = (opts.date ?? new Date()).toISOString().replace(/\.\d{3}Z$/, 'Z').replace(/[:-]/g, '');
+    const day = datetime.slice(0, 8);
+    const headers = { 'X-Date': datetime };
+    if (opts.credentials.sessionToken)
+        headers['X-Security-Token'] = opts.credentials.sessionToken;
+    if (opts.body !== undefined)
+        headers['X-Content-Sha256'] = sha256Hex(opts.body);
+    const names = Object.keys(headers).sort((a, b) => (a.toLowerCase() < b.toLowerCase() ? -1 : 1));
+    const canonicalHeaders = names.map((k) => `${k.toLowerCase()}:${headers[k].replace(/\s+/g, ' ').trim()}`).join('\n');
+    const signedHeaders = names.map((k) => k.toLowerCase()).sort().join(';');
+    const bodyHash = headers['X-Content-Sha256'] ?? sha256Hex('');
+    const canonical = [
+        opts.method.toUpperCase(),
+        '/',
+        canonicalQuery(opts.query),
+        `${canonicalHeaders}\n`,
+        signedHeaders,
+        bodyHash,
+    ].join('\n');
+    const scope = `${day}/${opts.region}/${SERVICE}/request`;
+    const stringToSign = ['HMAC-SHA256', datetime, scope, sha256Hex(canonical)].join('\n');
+    const key = hmac(hmac(hmac(hmac(opts.credentials.secretKey, day), opts.region), SERVICE), 'request');
+    const signature = createHmac('sha256', key).update(stringToSign).digest('hex');
+    headers.Authorization = `HMAC-SHA256 Credential=${opts.credentials.accessKeyId}/${scope}, SignedHeaders=${signedHeaders}, Signature=${signature}`;
+    return headers;
+}
+/** CRC-32/IEEE, which the store host checks via `Content-CRC32`. */
+const CRC_TABLE = (() => {
+    const t = new Uint32Array(256);
+    for (let i = 0; i < 256; i++) {
+        let c = i;
+        for (let k = 0; k < 8; k++)
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        t[i] = c >>> 0;
+    }
+    return t;
+})();
+export function crc32(buf) {
+    let crc = 0xffffffff;
+    for (let i = 0; i < buf.length; i++)
+        crc = CRC_TABLE[(crc ^ buf[i]) & 0xff] ^ (crc >>> 8);
+    return (crc ^ 0xffffffff) >>> 0;
+}
+async function callVod(token, action, opts) {
+    const host = process.env.WJI_VOD_HOST || DEFAULT_HOST;
+    const region = token.region || DEFAULT_REGION;
+    const query = { ...(opts.query || {}), Action: action, Version: VERSION };
+    const body = opts.json === undefined ? undefined : JSON.stringify(opts.json);
+    const headers = signVodRequest({
+        method: opts.method,
+        query,
+        body,
+        region,
+        credentials: {
+            accessKeyId: token.stsToken.AccessKeyId,
+            secretKey: token.stsToken.SecretAccessKey,
+            sessionToken: token.stsToken.SessionToken,
+        },
+    });
+    if (body !== undefined)
+        headers['Content-Type'] = 'application/json; charset=utf-8';
+    const res = await fetch(`https://${host}/?${canonicalQuery(query)}`, { method: opts.method, headers, body });
+    const text = await res.text();
+    let json;
+    try {
+        json = JSON.parse(text);
+    }
+    catch {
+        throw new Error(`VOD ${action}: HTTP ${res.status} ${text.slice(0, 200)}`);
+    }
+    const err = json?.ResponseMetadata?.Error;
+    if (err || !res.ok) {
+        throw new Error(`VOD ${action}: ${err?.Code || res.status} ${err?.Message || text.slice(0, 200)}`);
+    }
+    return json?.Result;
+}
+/**
+ * Upload one local video and return its Vid. One PUT of the whole file —
+ * fine for episode-sized files; the browser SDK's chunked mode is not
+ * reproduced, so very large masters (multi-GB) are better uploaded on the web.
+ */
+export async function uploadToVod(token, file, onProgress) {
+    const size = (await stat(file)).size;
+    const ext = extname(file).toLowerCase() || '.mp4';
+    onProgress?.('requesting an upload slot');
+    const applied = await callVod(token, 'ApplyUploadInfo', {
+        method: 'GET',
+        // No FileName: BytePlus uses it as the storage key, so a repeat name fails with AlreadyExisted.
+        query: { SpaceName: token.spaceName, FileType: 'media', FileSize: size, FileExtension: ext },
+    });
+    const addr = applied?.Data?.UploadAddress ?? applied?.UploadAddress;
+    const host = addr?.UploadHosts?.[0];
+    const store = addr?.StoreInfos?.[0];
+    if (!host || !store?.StoreUri || !addr?.SessionKey) {
+        throw new Error(`VOD ApplyUploadInfo returned no upload address: ${JSON.stringify(applied).slice(0, 300)}`);
+    }
+    const buffer = await readFile(file);
+    onProgress?.(`uploading ${(size / 1e6).toFixed(1)} MB`);
+    const put = await fetch(`https://${host}/${String(store.StoreUri).split('/').map(encodeURIComponent).join('/')}`, {
+        method: 'PUT',
+        headers: {
+            Authorization: store.Auth,
+            'Content-CRC32': crc32(buffer).toString(16).padStart(8, '0'),
+        },
+        body: new Uint8Array(buffer),
+    });
+    if (put.status !== 200) {
+        throw new Error(`VOD upload failed: HTTP ${put.status} ${(await put.text()).slice(0, 200)}`);
+    }
+    onProgress?.('committing');
+    const committed = await callVod(token, 'CommitUploadInfo', {
+        method: 'POST',
+        json: { SpaceName: token.spaceName, SessionKey: addr.SessionKey },
+    });
+    const vid = String(committed?.Data?.Vid || committed?.Vid || '').trim();
+    if (!vid)
+        throw new Error(`VOD CommitUploadInfo returned no Vid: ${JSON.stringify(committed).slice(0, 300)}`);
+    return vid;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wji.ai/cli",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Command line interface for the WJI AI platform",
   "license": "UNLICENSED",
   "author": "WJI AI",

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.