@wji.ai/cli 0.5.0 → 0.6.0

package/README.md

@@ -117,8 +117,12 @@ Run `wji <group> --help` for the full option list.
 
 ## Conventions
 
-- **`--json`** on any command prints the raw API response and nothing else, so
-  everything composes with `jq`.
+- **`--json`** on any command prints JSON and nothing else, so everything
+  composes with `jq`. List and get commands print the **`standard`** level by
+  default (ids, names, status, media urls, long text clipped to 200 chars,
+  `content` summarised with `truncated: true`). Add **`--detail full`** (or set
+  `WJI_DETAIL=full`) for the raw API response, `--detail brief` for id lists.
+  Human table output is never affected.
 - **`@file` and `-`** work anywhere a long text or JSON value is expected:
   `-p @prompt.txt`, `--content @node.json`, `-p -` to read stdin.
 - **`--set key=value`** sends arbitrary fields; dotted keys nest
@@ -244,6 +248,7 @@ Skill refs are `system:<key>` or `user:<skillId>` (a bare id is treated as `user
 | Generation submissions | image 30 / video 10 / audio 20 per minute, per user or key |
 | Generation queue | queued + running jobs: FREE 3 / VIP 10 / SVIP 25 → HTTP 429 |
 | Pagination | `--limit` ≤100; `-1` returns at most 500 except on opt-in endpoints |
+| Detail levels | `?detail=brief\|standard\|full` on workspace, fsnode, model and history reads; the API defaults to `full`, the CLI's `--json` to `standard` |
 | Batches | `asset status` is sent 100 ids at a time; `asset summary` ≤100 ids |
 | Skills | zip ≤5MB, ≤200 files, ≤2MB per `.md`, ≤20MB total, 50 per account |
 | Creation caps | 50 workspaces, 3 organizations per account |
@@ -290,6 +295,21 @@ upgrading the CLI so the skill matches the commands.
 pipeline (outline → characters → scenes/props → script → storyboard) whose
 stages are checked by `skill/short-drama/scripts/short-drama.mjs validate`,
 with the data stored as workspace datasets and the work laid out on canvases.
+
+`skill/ads/` and `skill/social-media/` are two more: `ads` makes commercials
+and ad creative (TVC / bumper / social ad formats and durations, product
+photography and studio lighting, visual styles, product identity across
+generations, banner sizes, AI-disclosure compliance); `social-media` holds
+every platform's image / video specs (Instagram, TikTok, YouTube, Facebook, X,
+LinkedIn, Pinterest, Threads, Snapchat, 小红书, 抖音, 快手, 视频号, B站, 微博,
+公众号) and the repurposing recipes — an episode into 9:16 teasers and posters,
+an ad master into every placement. Install them the same way:
+
+```bash
+cp -r "$(npm root -g)/@wji.ai/cli/skill/short-drama" ~/.claude/skills/short-drama
+cp -r "$(npm root -g)/@wji.ai/cli/skill/ads" ~/.claude/skills/ads
+cp -r "$(npm root -g)/@wji.ai/cli/skill/social-media" ~/.claude/skills/social-media
+```
 Install it the same way (`cp -r skill/short-drama ~/.claude/skills/short-drama`)
 next to `wji`; `node skill/short-drama/scripts/selftest.mjs` runs its self-test.
 

package/dist/commands/canvas.js

@@ -1,7 +1,7 @@
 import { Command } from 'commander';
 import { WjiClient } from '../core/client.js';
 import { confirm, parseKeyValues, readValue } from '../core/prompt.js';
-import { color, detail, info, isJsonMode, printJson, relativeTime, render, success, table, truncate, warn } from '../core/output.js';
+import { clipText, color, detail, detailLevel, info, isJsonMode, printJson, relativeTime, render, success, table, truncate, warn } from '../core/output.js';
 import { pollHistory, reportHistory, resolveAssets } from './gen.js';
 import { loadMembers, memberLabel, resolveMember } from '../core/members.js';
 import { fetchModels } from './model.js';
@@ -315,6 +315,53 @@ export function describe(canvas, node) {
         outgoing: canvas.edges.filter((e) => e.fromNodeId === node.id).map((e) => e.toNodeId),
     };
 }
+/**
+ * The canvas commands always load the full canvas (edits and generation need
+ * every field), so --detail is applied here, to the JSON they print. Mirrors
+ * the backend's canvas_list_nodes levels.
+ */
+export function trimDescribed(row, level = detailLevel()) {
+    if (!level || level === 'full')
+        return row;
+    if (level === 'brief') {
+        return compactRow({
+            id: row.id,
+            kind: row.kind,
+            name: row.name,
+            tag: row.tag,
+            mode: row.mode,
+            status: row.status,
+            assetId: row.assetId,
+            position: row.position,
+            references: row.references.map((r) => ({ nodeId: r.nodeId, label: r.label })),
+            outgoing: row.outgoing,
+        });
+    }
+    const g = row.generate;
+    return compactRow({
+        ...row,
+        text: row.text === undefined ? undefined : clipText(row.text) ?? '',
+        error: typeof row.error === 'string' ? clipText(row.error) : row.error,
+        generate: g
+            ? compactRow({
+                prompt: clipText(g.prompt),
+                model: g.model,
+                ratio: g.ratio,
+                resolution: g.resolution,
+                duration: g.duration,
+                historyId: g.historyId,
+                pendingAssetId: g.pendingAssetId,
+            })
+            : undefined,
+    });
+}
+function compactRow(value) {
+    const out = {};
+    for (const key of Object.keys(value))
+        if (value[key] !== undefined)
+            out[key] = value[key];
+    return out;
+}
 // ── models ──────────────────────────────────────────────────────────────────
 /** An audio node is fed by either an `audio` or a `tts` model — the backend tags voice models `tts`. */
 const KIND_FEATURES = { audio: ['audio', 'tts'] };
@@ -1022,7 +1069,7 @@ export function canvasCommand(globals) {
                 .filter((id) => loaded.byId.has(id))
                 .map((id) => describe(loaded, loaded.byId.get(id)));
         }
-        const out = { ...res, state: { ...state, canvasName }, selected };
+        const out = { ...res, state: { ...state, canvasName }, selected: selected.map((n) => trimDescribed(n)) };
         render(out, () => {
             const seconds = Math.max(0, Math.round((new Date(state.expiresAt).getTime() - Date.now()) / 1000));
             detail([
@@ -1249,7 +1296,7 @@ export function canvasCommand(globals) {
             .filter((n) => !nameRe || nameRe.test(n.name))
             .map((n) => describe(cv, n))
             .filter((n) => (colors ? !!n.tag && colors.has(n.tag.color) : opts.untagged ? !n.tag : true));
-        render({ canvas: { id: cv.id, name: cv.name, workspaceId: cv.workspaceId }, nodes: rows }, () => {
+        render({ canvas: { id: cv.id, name: cv.name, workspaceId: cv.workspaceId }, nodes: rows.map((n) => trimDescribed(n)) }, () => {
             info(color.dim(`${cv.name} (${cv.id}) · ${rows.length} node(s) · ${cv.edges.length} edge(s)`));
             nodeTable(rows);
         });
@@ -1283,13 +1330,13 @@ export function canvasCommand(globals) {
     });
     canvas
         .command('get <nodeId>')
-        .description('One node in full, with its references')
+        .description('One node with its references (--detail full for the whole generate / text)')
         .option('-c, --canvas <id>', 'canvas id (defaults to the linked canvas)')
         .action(async (id, opts) => {
         const c = client();
         const cv = await loadCanvas(c, await resolveCanvasId(c, opts.canvas));
         const n = describe(cv, requireNode(cv, id));
-        render(n, () => printNode(n));
+        render(trimDescribed(n), () => printNode(n));
     });
     canvas
         .command('edges')

package/dist/commands/fsnode.js

@@ -1,7 +1,7 @@
 import { Command } from 'commander';
 import { WjiClient } from '../core/client.js';
 import { confirm, parseKeyValues, readJson, readValue } from '../core/prompt.js';
-import { color, detail, info, relativeTime, render, success, table, truncate } from '../core/output.js';
+import { color, detail, detailLevel, info, relativeTime, render, success, table, truncate } from '../core/output.js';
 import { printTree } from './workspace.js';
 /** Nested plain objects merge; arrays and scalars are replaced. */
 function deepMerge(base, patch) {
@@ -22,7 +22,10 @@ export function fsCommand(globals) {
         .action(async (key, opts) => {
         const client = new WjiClient(globals());
         const path = key ? `/fsnode/root/${key}` : '/fsnode/root';
-        const node = await client.get(path, opts.depth ? { depth: Number(opts.depth) } : undefined);
+        const node = await client.get(path, {
+            depth: opts.depth ? Number(opts.depth) : undefined,
+            detail: detailLevel(),
+        });
         render(node, (n) => (opts.depth ? printTree(n) : printNode(n)));
     });
     fs.command('ls <id>')
@@ -34,6 +37,7 @@ export function fsCommand(globals) {
         const result = await client.get(`/fsnode/list/${id}/children`, {
             limit: opts.limit ? Number(opts.limit) : undefined,
             scope: opts.scope,
+            detail: detailLevel(),
         });
         const rows = Array.isArray(result) ? result : result?.data || [];
         render(result, () => table(rows, [
@@ -50,15 +54,18 @@ export function fsCommand(globals) {
         .option('-d, --depth <n>', 'levels to expand')
         .action(async (id, opts) => {
         const client = new WjiClient(globals());
-        const node = await client.get(`/fsnode/list/${id}/tree`, opts.depth ? { depth: Number(opts.depth) } : undefined);
+        const node = await client.get(`/fsnode/list/${id}/tree`, {
+            depth: opts.depth ? Number(opts.depth) : undefined,
+            detail: detailLevel(),
+        });
         render(node, (n) => printTree(n));
     });
     fs.command('get <id>')
-        .description('Show one node (comma-separate ids for a batch)')
+        .description('Show one node (comma-separate ids for a batch; --detail full for the whole content)')
         .option('--scope <scope>', 'server-side scope filter')
         .action(async (id, opts) => {
         const client = new WjiClient(globals());
-        const node = await client.get(`/fsnode/list/${id}`, { scope: opts.scope });
+        const node = await client.get(`/fsnode/list/${id}`, { scope: opts.scope, detail: detailLevel() });
         render(node, (n) => (Array.isArray(n) ? n.forEach(printNode) : printNode(n)));
     });
     fs.command('path <id>')
@@ -232,7 +239,7 @@ export function datasetCommand(globals) {
         .description('List dataset nodes in a folder')
         .action(async (folderId) => {
         const client = new WjiClient(globals());
-        const result = await client.get(`/fsnode/list/${folderId}/children`);
+        const result = await client.get(`/fsnode/list/${folderId}/children`, { detail: detailLevel() });
         const rows = (Array.isArray(result) ? result : result?.data || []).filter((n) => n.mimetype === 'workspace/dataset' || n.type === 'file');
         render(rows, () => table(rows, [
             { header: 'id', value: (n) => n.id },

package/dist/commands/gen.js

@@ -1,7 +1,7 @@
 import { Command } from 'commander';
 import { WjiClient } from '../core/client.js';
 import { confirm, parseKeyValues, readJson, readValue } from '../core/prompt.js';
-import { color, detail, info, isJsonMode, printJson, render, success, table, truncate, warn } from '../core/output.js';
+import { color, detail, detailLevel, info, isJsonMode, printJson, render, success, table, truncate, warn } from '../core/output.js';
 const READY = 1;
 const CANCELLED = -1;
 /** `--ref abc123`, `--ref abc123:hero`, `--ref abc123:hero:0.6` */
@@ -254,6 +254,7 @@ export function historyCommand(globals) {
             bookmarked: opts.bookmarked ? true : undefined,
             page: Number(opts.page),
             limit: Number(opts.limit),
+            detail: detailLevel(),
         });
         render(result, (r) => {
             table(r.data || [], [
@@ -284,7 +285,7 @@ export function historyCommand(globals) {
             }));
         }
         else {
-            history = await client.get(`/ai/assets/history/list/${id}`);
+            history = await client.get(`/ai/assets/history/list/${id}`, { detail: detailLevel() });
             assets = await resolveAssets(client, history);
         }
         render({ ...history, images: assets }, () => reportHistory(history, assets));

package/dist/commands/model.js

@@ -1,6 +1,6 @@
 import { Command } from 'commander';
 import { WjiClient } from '../core/client.js';
-import { color, detail, info, render, table, truncate, warn } from '../core/output.js';
+import { color, detail, detailLevel, info, render, table, truncate, warn } from '../core/output.js';
 const FEATURES = [
     'text',
     'image',
@@ -24,6 +24,7 @@ export async function fetchModels(client, opts) {
     const features = opts.features?.length ? opts.features : FEATURES;
     const list = await client.get(`/ai/model/list/${features.join(',')}`, {
         workspaceId: client.workspace(opts.workspace),
+        detail: opts.detail,
     });
     return Array.isArray(list) ? list : list?.data || [];
 }
@@ -41,6 +42,7 @@ export function modelCommand(globals) {
         let rows = await fetchModels(client, {
             features: opts.feature,
             workspace: opts.workspace,
+            detail: detailLevel(),
         });
         if (!opts.all)
             rows = rows.filter((m) => m.enabled !== false && !m.hidden);
@@ -70,7 +72,7 @@ export function modelCommand(globals) {
         .option('-w, --workspace <id>', 'resolve pricing/access for a workspace')
         .action(async (name, opts) => {
         const client = new WjiClient(globals());
-        const rows = await fetchModels(client, { workspace: opts.workspace });
+        const rows = await fetchModels(client, { workspace: opts.workspace, detail: detailLevel() });
         // `name` is not unique across providers; `nickname` is, so prefer it.
         const matches = rows.filter((m) => m.nickname === name || m.name === name);
         if (!matches.length)

package/dist/commands/workspace.js

@@ -2,7 +2,7 @@ import { Command } from 'commander';
 import { WjiClient } from '../core/client.js';
 import { updateProfile } from '../core/config.js';
 import { confirm, parseKeyValues } from '../core/prompt.js';
-import { color, detail, info, relativeTime, render, success, table, truncate } from '../core/output.js';
+import { color, detail, detailLevel, info, relativeTime, render, success, table, truncate } from '../core/output.js';
 import { loadMembers, memberLabel, resolveMember } from '../core/members.js';
 /** App tokens accepted by `--app`; mirrors WorkspaceApplication on the backend. */
 const APPS = {
@@ -54,6 +54,7 @@ export function workspaceCommand(globals) {
             scope: opts.scope,
             page: Number(opts.page),
             limit: Number(opts.limit),
+            detail: detailLevel(),
         });
         const current = client.workspace();
         render(result, (r) => {
@@ -77,7 +78,9 @@ export function workspaceCommand(globals) {
         .description('Show a workspace (defaults to the selected one)')
         .action(async (id) => {
         const client = new WjiClient(globals());
-        const w = await client.get(`/workspace/list/${client.requireWorkspace(id)}`);
+        const w = await client.get(`/workspace/list/${client.requireWorkspace(id)}`, {
+            detail: detailLevel(),
+        });
         render(w, () => detail([
             ['id', w.id],
             ['name', w.name],
@@ -173,7 +176,7 @@ export function workspaceCommand(globals) {
         const path = opts.app
             ? `/workspace/list/${wsId}/fs/${opts.app}`
             : `/workspace/list/${wsId}/fs`;
-        const root = await client.get(path);
+        const root = await client.get(path, { detail: detailLevel() });
         render(root, (node) => printTree(node));
     });
     // ── apps ───────────────────────────────────────────────────────────────────

package/dist/core/output.js

@@ -17,6 +17,35 @@ export function setJsonMode(on) {
 export function isJsonMode() {
     return jsonMode;
 }
+const DETAIL_LEVELS = ['brief', 'standard', 'full'];
+/**
+ * Global --detail (or WJI_DETAIL). Unset means "standard when printing JSON,
+ * nothing (server default = full) for human output", so tables are unchanged.
+ */
+let detailMode;
+export function setDetailMode(raw) {
+    if (raw === undefined || raw === '') {
+        detailMode = undefined;
+        return;
+    }
+    const level = String(raw).toLowerCase();
+    if (!DETAIL_LEVELS.includes(level)) {
+        throw new Error(`--detail must be one of ${DETAIL_LEVELS.join(', ')} (got "${raw}")`);
+    }
+    detailMode = level;
+}
+export function detailLevel() {
+    if (detailMode)
+        return detailMode;
+    return jsonMode ? 'standard' : undefined;
+}
+/** Clip long text the way the server does at `standard` (200 chars + …). */
+export function clipText(value, max = 200) {
+    if (value === undefined || value === null || value === '')
+        return undefined;
+    const s = String(value);
+    return s.length <= max ? s : `${s.slice(0, max)}…`;
+}
 export function printJson(value) {
     process.stdout.write(JSON.stringify(value, null, 2) + '\n');
 }

package/dist/index.js

@@ -2,7 +2,7 @@
 import { createRequire } from 'node:module';
 import { Command } from 'commander';
 import { ApiError } from './core/client.js';
-import { color, setJsonMode } from './core/output.js';
+import { color, setDetailMode, setJsonMode } from './core/output.js';
 import { authCommand } from './commands/auth.js';
 import { configCommand } from './commands/config.js';
 import { orgCommand } from './commands/org.js';
@@ -34,7 +34,8 @@ program
     .option('--org <orgId>', 'organization context (X-Org-Id)')
     .option('--no-org', 'force personal context')
     .option('--locale <locale>', 'response language (cht, chs, en)')
-    .option('--json', 'print raw JSON instead of tables')
+    .option('--json', 'print JSON instead of tables (standard detail unless --detail is given)')
+    .option('--detail <level>', 'how much to return: brief | standard | full (default standard for --json; env WJI_DETAIL)')
     .configureHelp({ sortSubcommands: true });
 /**
  * Global flags live on the root command, but subcommand actions run before
@@ -51,10 +52,12 @@ const globals = () => {
         // commander turns `--no-org` into org === false
         personal: opts.org === false,
         locale: opts.locale,
+        detail: opts.detail,
     };
 };
 program.hook('preAction', () => {
     setJsonMode(!!program.opts().json);
+    setDetailMode(program.opts().detail ?? process.env.WJI_DETAIL);
 });
 program.addCommand(authCommand(globals));
 program.addCommand(configCommand(globals));

package/package.json

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

package/skill/ads/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: ads
+description: Make commercials and ad creative with AI on WJI through the `wji` CLI — video ads (TVC 15 / 30 / 60 s, 6-second bumpers, skippable and non-skippable pre-roll, 9–34 s social ads, product demos, UGC-style, testimonials, explainers) and ad images (product shots / 产品图, key visuals / 主视觉 KV, display banners), with studio lighting and product-photography vocabulary, visual styles by industry, second-by-second ad structure (hook in 3 s, brand by 5 s, CTA card), product identity locked across every generation, deliverables per placement and AI-disclosure compliance. Use whenever a task mentions an ad / 广告 / 廣告, a commercial, TVC, product shot, packshot, banner, key visual, promo / 宣传片 or brand video. Hands per-platform sizes to the social-media skill. Works together with the `wji` skill.
+---
+
+# Ads on WJI
+
+One brief, one canvas, one master. **You write the brief, the concept and every prompt**; the
+`wji` CLI keeps the brief as a dataset, lays the work out on a canvas and generates the stills
+and clips. Nothing is generated until the brief is complete and the user has said yes to the
+quote (or the message carried `-auto`, see the `wji` skill).
+
+```
+brief ──▶ concept & hooks ──▶ key visual / storyboard ──▶ stills ──▶ clips ──▶ master + deliverables
+  │            │                    │                        │          │            │
+ brief.md   3–5 hooks,           shot list with           product-   image-to-   ratio variants,
+ + story/   framework,           timecodes, one           locked     video,      overlays, end card
+ dataset    CTA & end card       master ratio             KV + keys  3–8 s each  → social-media skill
+```
+
+`{baseDir}` = this skill. Read `{baseDir}/reference/brief-template.md` before asking the user
+anything and `{baseDir}/reference/formats-video.md` or `formats-image.md` before proposing a format.
+The `wji` skill governs every CLI call (auth, confirmations, spending policy, model choice).
+
+| Read | When |
+| --- | --- |
+| `reference/brief-template.md` | before the first question — the fields, and what a complete brief looks like |
+| `reference/formats-video.md` | choosing a video format, its length and second-by-second structure; cutting the ad into clips |
+| `reference/formats-image.md` | a KV, packshot or banner: IAB / Google / Meta sizes, text limits, generate-then-crop |
+| `reference/product-photography.md` | writing any product still: lighting setups, shot types, backgrounds, lens, grade, the prompt template |
+| `reference/styles.md` | picking the look — 13 styles with signifiers and prompt phrases, by industry |
+| `reference/ai-consistency.md` | before generating: how the product stays the same across stills and clips, what never to generate |
+| `reference/models.md` | which WJI model for which need (ratios, resolutions, references, text in image, transparent background) |
+| `reference/compliance.md` | before delivery: AI-content labels per platform / jurisdiction, misleading-depiction rules |
+
+## Operations
+
+### Where the brief lives
+
+Locally: an `ads/<product>/` folder with `brief.md` (the brief, concept, shot list and
+deliverables — one file, sections in that order) and `prompts/` (one text file per still and
+clip, so `--prompt-file` can send them verbatim). On WJI: the same brief as a dataset in the
+workspace's **story** folder, so the canvas and the chat see it.
+
+```bash
+wji auth whoami --json && wji profile wallet            # preflight; an ad is a handful of stills + 4–8 clips
+wji ws use <workspaceId>                                 # or wji ws create "<product> ads" -r 16:9
+wji ws app list                                          # the Dataset app id → DS_APP
+wji --json ws fs --app DS_APP | jq -r '.. | objects | select(.content.semanticKey? == "story") | .id'   # → STORY
+wji dataset new STORY "AD <product>" -t other -d "<one line>" --json | jq -r .id                       # → BRIEF
+wji fs set BRIEF --merge content=@ads/<product>/brief.md --merge viewMode=content                      # the brief text
+wji asset upload ads/<product>/packshot.png              # the user's product photo → PACK asset id
+wji models get <model>                                   # confirm ratios and the reference cap before promising a size
+```
+
+### The canvas
+
+One canvas per ad, `AD · <product>`, rows top to bottom:
+
+| Row | Nodes | Command |
+| --- | --- | --- |
+| 1 references | the packshots and brand assets | `wji canvas add image -c CV -n "packshot" --asset PACK --at 0,0` (display nodes) |
+| 2 key visuals | one image node per style / hook variant | `wji canvas add image -c CV -n "KV minimal" --from P1 -m <image model> -r 1:1 --resolution 2K --prompt-file prompts/kv-minimal.txt --at 0,400` — the packshot node is always **first** in `--from` (`@image1`) |
+| 3 storyboard stills | one per clip, in order | same, `--from P1 KV1` so light and grade carry over |
+| 4 clips | one video node per still | `wji canvas add video -c CV -n "clip 01" --from S1 P1 -m <video model> -r 16:9 -d 5 --prompt-file prompts/clip-01.txt` |
+| 5 copy | headline / CTA / legal lines | `wji canvas add text -c CV --text-file ads/<product>/overlays.md --plain` beside the clip they belong to — overlays are added in the edit, **never generated into the picture** |
+
+`--from` order sets `@imageN`; `wji canvas connect <from> <to>` adds a reference later. Quote
+first — `wji canvas gen <nodeIds…>` prints the cost and refuses — tell the user, then
+`wji canvas gen <nodeIds…> --yes --wait` after the yes. `wji canvas set <node> -p … / -r … / -d …`
+changes a node without rebuilding it; `wji canvas get <node> --json | jq -r .assetId` then
+`wji asset download <asset> -o /tmp/ad` to look at a result before approving it.
+
+For a one-off still with no canvas: `wji gen image -m <model> -p "…" -r 1:1 --ref PACK --wait`
+— it still needs the user's yes first unless the message carried `-auto`.
+
+Take ids from the command's own JSON (`wji --json canvas add … | jq -r .id`), never by searching
+names. Ratio, resolution and duration are validated against the model — copy the spelling from
+`wji models get`.
+
+## Before anything else
+
+1. **Read the brief template**, then **ask for what is missing in one message**: product (and a
+   packshot or product photo — without one the product cannot be kept consistent), audience,
+   objective (awareness / conversion / retargeting), format and length, placements and their
+   ratios, style, brand colours (hex), must-show / must-say, CTA, legal lines, whether the ad
+   will run where AI content must be labelled. Offer defaults where the user has none
+   (`reference/formats-video.md` §"Formats at a glance", `reference/styles.md` §"Choosing by industry"), but
+   **do not generate anything without the product reference and the placement**.
+2. **Write `brief.md`** and push it as the `AD <product>` dataset. Everything later reads from it.
+3. **Confirm the master ratio**: 16:9 when the primary placement is YouTube / TV / display,
+   9:16 when it is Reels / TikTok / Shorts / 抖音, 1:1 or 4:5 for feed-only. One master; the
+   other ratios are made later (stills regenerated or cropped, video regenerated — see
+   `reference/formats-image.md` §"Generate, then crop" and the social-media skill).
+4. **Check the wallet and quote** (`wji gen cost`) before every generation; say what the whole
+   plan will cost before starting row 2.
+
+## Stage 1 — Concept
+
+- Pick the framework (`reference/formats-video.md`): AIDA for cold audiences and launches, PAS
+  for retargeting, ABCD as the checklist for anything on YouTube. Write **3–5 hooks** (first
+  3 seconds), pick one with the user, keep the others as A/B variants.
+- Write the **shot list with timecodes**: hook 0–3 s, product in frame by 3 s, brand by 5 s,
+  proof / demo, CTA card in the last 2–5 s. Sound-off first: every beat must read with captions
+  and no audio.
+- Cut the ad into **clips of 3–8 s**, each one generation, sized to the video model
+  (`reference/models.md`: h3 5–15 s fixed, seedance-2.5 4–30 s auto, wan 2–30 s, veo 4–8 s,
+  kling 3–15 s). A 15-s vertical ad is typically 3 clips + end card; a 30-s TVC 5–7 clips.
+- For an **image-only** job (KV, banner set, packshot variants) the concept is the layout: where
+  the product sits, where the headline zone stays clear, which sizes are needed
+  (`reference/formats-image.md`).
+- Put the concept into `brief.md` (`## Concept`, `## Shot list`, `## Deliverables`) and
+  `wji fs set BRIEF --merge content=@ads/<product>/brief.md`.
+
+## Stage 2 — Key visual and stills
+
+- Build row 1 (packshots, brand refs) and row 2 (one KV per style variant, 2–3 at most). Every
+  prompt follows `reference/product-photography.md` §"The prompt template": subject → shot → lighting
+  → background → camera → grade → constraints, and ends with the identity line from
+  `reference/ai-consistency.md` ("keep the label, shape and colour of @image1 exactly …").
+- Pick the model by need (`reference/models.md`): legible text in the picture → nano-banana-pro /
+  gpt-image-2.5 / seedream-5-pro; transparent background for a logo or cut-out → gpt-image-2.5
+  with `--set background=transparent`; 4:5 or 2:3 placements → nano-banana / flux-2-flex /
+  seedream-5; a marketing look out of the box → marketing-studio-image. Default
+  `--resolution 2K` for a KV, `1K` while exploring.
+- **Never generate** legal text, small print, prices that must be exact, or a real logo — those
+  are text nodes and overlays. Headline text may be generated only to preview a layout.
+- Download and look at the KVs, show the user, take the pick, then generate row 3 (storyboard
+  stills) `--from P1 KV1` so light direction, grade and lens stay the same across the ad.
+- Quality pass before any clip: hands on the product, label text, logo drift, product proportions,
+  impossible physics (`reference/ai-consistency.md` §"Artefact checklist"). Regenerate a still
+  rather than trying to fix it in the clip.
+
+## Stage 3 — Clips
+
+- One video node per approved still, `--from S1 P1`, `-d` from the shot list (whole seconds),
+  master `-r`. Prompts describe **motion and camera only** — the look is already in the still;
+  repeat the product-identity line.
+- Product in frame for the whole clip unless the shot list says otherwise; no text in the video
+  prompt (captions and CTA are overlays).
+- Voice-over and music: `wji canvas add audio -c CV -m seed-audio-1.0 --prompt-file prompts/vo.txt`
+  when the user wants a VO bed; the script lines come from the brief's must-say.
+- Quote the whole row, generate after the yes, download and review every clip against the still
+  it came from (same product, same light), regenerate the ones that drift.
+
+## Stage 4 — Master and deliverables
+
+- The master is the clip sequence + overlay text in order; assembling the cut, captions and
+  overlays happens in the user's editor (or locally with ffmpeg when it is installed and the user
+  asks) — list the timeline explicitly (clip → seconds → overlay text) in `## Deliverables`.
+- **Other ratios**: stills are regenerated at the placement ratio (or cropped when the ratio is
+  not native, `reference/formats-image.md`), video is **regenerated** at the placement ratio
+  from the same stills — never cropped. When the social-media skill is installed, hand it the
+  brief and the canvas; it owns the per-platform spec sheet. Otherwise list the sizes yourself
+  from `reference/formats-image.md`.
+- **Compliance** (`reference/compliance.md`): say whether the ad needs an AI-content label on
+  each placement, and never depict a result the product cannot deliver.
+
+## Reporting
+
+After each stage: what is on the canvas (row, node names), what was spent, what the user must
+decide next (pick a KV, approve the shot list, approve a clip). After delivery: the deliverables
+table (file, ratio, duration, overlay text, label needed) and the A/B variants still unbuilt.
+
+## Rules specific to this skill
+
+- **Ask before every generation**, even one image (the `wji` skill's spending policy is the
+  floor; this skill asks for images too, because an ad's stills are its most expensive mistakes).
+- **The packshot is `@image1` in every generation** — stills and clips. No packshot, no
+  generation; ask for one or generate a packshot first and have the user approve it.
+- One master ratio per ad; variants are separate rows, never reframes of the master.
+- Text, prices, legal lines and logos are overlays, never generated pixels.
+- Do not invent platform limits or sizes — cite the row in `reference/formats-video.md` /
+  `reference/formats-image.md`; rows marked *(verify)* are said as such.
+- All-audiences content only, no real people's likeness without the user's confirmation that they have the
+  rights, no competitor products in frame.