@wji.ai/cli 0.6.0 → 0.7.0

package/dist/commands/workspace.js

@@ -1,9 +1,10 @@
 import { Command } from 'commander';
 import { WjiClient } from '../core/client.js';
-import { updateProfile } from '../core/config.js';
+import { getProfile, updateProfile } from '../core/config.js';
 import { confirm, parseKeyValues } from '../core/prompt.js';
 import { color, detail, detailLevel, info, relativeTime, render, success, table, truncate } from '../core/output.js';
 import { loadMembers, memberLabel, resolveMember } from '../core/members.js';
+import { fetchModels } from './model.js';
 /** App tokens accepted by `--app`; mirrors WorkspaceApplication on the backend. */
 const APPS = {
     dataset: 'Dataset',
@@ -342,6 +343,56 @@ export function workspaceCommand(globals) {
             await client.delete(`/workspace/list/${wsId}/member/${m.memberId}`);
         render({ removed: targets.map((m) => m.userId) }, () => success(`Removed ${names}`));
     });
+    ws.command('leave <id>')
+        .description('Leave a workspace you were invited to (owners cannot leave)')
+        .option('-y, --yes', 'skip confirmation')
+        .action(async (id, opts) => {
+        const g = globals();
+        const client = new WjiClient(g);
+        const w = await client.get(`/workspace/list/${id}/basic`).catch(() => ({ name: id }));
+        if (!(await confirm(`Leave workspace "${w.name}" (${id})? You need a new invite to come back.`, opts.yes))) {
+            return info('Aborted');
+        }
+        const result = await client.post(`/workspace/list/${id}/leave`);
+        // A left workspace 403s from now on, so stop pointing the profile at it.
+        if (getProfile(g.profile).profile.workspace === id)
+            updateProfile(g.profile, { workspace: undefined });
+        render(result, () => success(`Left ${w.name} (${id})`));
+    });
+    // ── default models ─────────────────────────────────────────────────────────
+    ws.command('defaults [id]')
+        .description('Show or set the workspace default models (pass "none" to clear one)')
+        .option('--chat <model>', 'default chat model for new conversations')
+        .option('--image <model>', 'default image model')
+        .option('--video <model>', 'default video model')
+        .option('--storyboard <model>', 'default storyboard model')
+        .option('--audio <model>', 'default audio model')
+        .option('--image-resolution <value>', 'default image resolution, e.g. 2K')
+        .option('--video-resolution <value>', 'default video resolution, e.g. 720p')
+        .action(async (id, opts) => {
+        const client = new WjiClient(globals());
+        const wsId = client.requireWorkspace(id);
+        // settings only comes back at full detail, and PUT replaces settings whole —
+        // read it fresh so prompts / defaultApp / improvePromptDefault survive.
+        const w = await client.getFresh(`/workspace/list/${wsId}`, { detail: 'full' });
+        const current = { ...(w.settings?.defaultModels || {}) };
+        const changes = DEFAULT_MODEL_KEYS.filter((key) => opts[key] !== undefined);
+        if (!changes.length) {
+            return render(current, () => detail(DEFAULT_MODEL_KEYS.map((key) => [key, current[key] ?? color.dim('—')])));
+        }
+        const next = { ...current };
+        const needsModels = changes.some((key) => !key.endsWith('Resolution') && !isNone(opts[key]));
+        const models = needsModels ? await fetchModels(client, { workspace: wsId }) : [];
+        for (const key of changes) {
+            const raw = String(opts[key]).trim();
+            next[key] = isNone(raw) ? null : key.endsWith('Resolution') ? raw : resolveDefaultModel(models, key, raw);
+        }
+        await client.put(`/workspace/list/${wsId}`, { settings: { ...(w.settings || {}), defaultModels: next } });
+        render(next, () => {
+            success('Default models updated');
+            detail(DEFAULT_MODEL_KEYS.map((key) => [key, next[key] ?? color.dim('—')]));
+        });
+    });
     // ── quota / stats ──────────────────────────────────────────────────────────
     ws.command('quota [id]')
         .description('Show credit quota usage')
@@ -384,6 +435,28 @@ export function workspaceCommand(globals) {
     });
     return ws;
 }
+const DEFAULT_MODEL_KEYS = [
+    'chat',
+    'image',
+    'video',
+    'storyboard',
+    'audio',
+    'imageResolution',
+    'videoResolution',
+];
+const isNone = (value) => ['none', 'null', ''].includes(String(value ?? '').trim().toLowerCase());
+/**
+ * The web stores the chat default as the model `name` (what conversations carry)
+ * and the media defaults as the `nickname` its pickers emit — the value `-m` takes.
+ * Accept either spelling and store what the web would.
+ */
+function resolveDefaultModel(models, key, value) {
+    const model = models.find((m) => m.nickname === value || m.name === value);
+    if (!model) {
+        throw new Error(`Unknown model "${value}" for --${key}. See \`wji models list\`.`);
+    }
+    return key === 'chat' ? model.name : model.nickname || model.name;
+}
 export function printTree(node, prefix = '', connector = '') {
     if (!node)
         return;

package/dist/core/backreel.js

@@ -0,0 +1,23 @@
+import { WjiClient } from './client.js';
+export const POSTS = '/backreel/post';
+/** BackreelAccessTier, lowest to highest. `owner` is internal and never set. */
+export const TIERS = ['public', 'member', 'supporter', 'partner'];
+/** Every Backreel call says `X-App: backreel`, so notifications and mail link to Backreel, not WJI. */
+export const backreelClient = (globals) => new WjiClient({ ...globals(), app: 'backreel' });
+/** The owner's view of a post (episodes with vodVid / video ids, campaign internals, donation config). */
+export const loadPost = (client, id) => client.getFresh(`${POSTS}/list/${id}`);
+export function oneOf(value, allowed, flag) {
+    if (!allowed.includes(value))
+        throw new Error(`${flag} must be one of ${allowed.join(', ')}`);
+    return value;
+}
+/** Ref fields come back as an id or a populated object; the API takes the id. */
+export const idOf = (ref) => (ref && typeof ref === 'object' ? ref.id : ref) || undefined;
+/** `n` on the command line is 1-based; returns the 0-based index or throws. */
+export function episodeIndex(n, count) {
+    const i = Number(n);
+    if (!Number.isInteger(i) || i < 1 || i > count) {
+        throw new Error(`Episode ${n} does not exist — this post has ${count} episode(s)`);
+    }
+    return i - 1;
+}

package/dist/core/client.js

@@ -3,6 +3,21 @@ import { basename } from 'node:path';
 import { DEFAULT_ENDPOINT, acquireLock, getProfile, refreshLockPath, releaseLock, updateProfile, } from './config.js';
 /** Server cap on `ids` for `/assets/check-status`, `/assets/summary/batch` and friends. */
 export const ASSET_BATCH_MAX_IDS = 100;
+/**
+ * Content types for multipart uploads. Some endpoints (Backreel private files)
+ * accept a file by its declared type alone, and a bare Blob is sent as
+ * application/octet-stream — which they reject as an unsupported type.
+ */
+const MIME_TYPES = {
+    png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', webp: 'image/webp', gif: 'image/gif', avif: 'image/avif',
+    mp4: 'video/mp4', mov: 'video/quicktime', m4v: 'video/x-m4v', webm: 'video/webm',
+    mp3: 'audio/mpeg', wav: 'audio/wav', m4a: 'audio/mp4',
+    pdf: 'application/pdf', csv: 'text/csv', txt: 'text/plain', md: 'text/markdown', json: 'application/json', zip: 'application/zip',
+    docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+};
+export const mimeTypeOf = (filename) => MIME_TYPES[filename.split('.').pop()?.toLowerCase() || ''] || 'application/octet-stream';
 export const isObjectId = (value) => /^[a-f0-9]{24}$/i.test(value);
 export class ApiError extends Error {
     status;
@@ -92,6 +107,8 @@ export class WjiClient {
         const org = this.orgId;
         if (org)
             headers['X-Org-Id'] = org;
+        if (this.globals.app)
+            headers['X-App'] = this.globals.app;
         return headers;
     }
     async request(method, path, opts = {}) {
@@ -175,7 +192,7 @@ export class WjiClient {
     /** Multipart upload of an in-memory buffer (e.g. a zip built on the fly). */
     async uploadBuffer(path, buffer, filename, fields = {}, field = 'file') {
         const form = new FormData();
-        form.append(field, new Blob([new Uint8Array(buffer)]), filename);
+        form.append(field, new Blob([new Uint8Array(buffer)], { type: mimeTypeOf(filename) }), filename);
         for (const [key, value] of Object.entries(fields)) {
             if (value !== undefined && value !== null && value !== '')
                 form.append(key, value);

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/dist/index.js

@@ -23,6 +23,12 @@ import { backreelCommand } from './commands/backreel.js';
 // Read from package.json so `wji --version` cannot drift from the published
 // version — the skill compares the two to detect a stale install.
 const VERSION = createRequire(import.meta.url)('../package.json').version;
+// `wji … | head` closes the pipe early; that is the reader being done, not a crash.
+process.stdout.on('error', (err) => {
+    if (err.code === 'EPIPE')
+        process.exit(0);
+    throw err;
+});
 const program = new Command();
 program
     .name('wji')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wji.ai/cli",
-  "version": "0.6.0",
+  "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.