@series-a/cli 1.3.0 → 1.3.2

package/src/commands/auth.mjs

@@ -0,0 +1,193 @@
+import prompts from "prompts";
+import chalk from "chalk";
+import { getProfile, setProfiles, listProfiles, deleteProfile, allProfiles, CONFIG_PATH, DEFAULTS } from "../config.mjs";
+import { call } from "../api.mjs";
+import { emit, fail, ctxFrom, withCommonOpts } from "../ui.mjs";
+
+/**
+ * Replacing the "default" profile silently re-points every unqualified command
+ * at another workspace. Always confirm first; in a non-interactive shell the
+ * caller must pass --force.
+ */
+async function confirmDefaultReplacement(workspace, opts, currentWorkspace) {
+  if (opts.force) return true;
+  if (!currentWorkspace) return true;
+  if (!process.stdin.isTTY) {
+    process.stdout.write(chalk.yellow(
+      `\n! Default profile currently points at workspace ${currentWorkspace}.\n` +
+      `  Not replacing it — re-run with --force to move it to ${workspace}.\n`,
+    ));
+    return false;
+  }
+  const r = await prompts({
+    type: "confirm",
+    name: "v",
+    message: `Replace the default profile (workspace ${currentWorkspace}) with ${workspace}?`,
+    initial: false,
+  });
+  return !!r.v;
+}
+
+export function registerAuth(program) {
+  program
+    .command("login")
+    .description("Save an API key + workspace to ~/.advisoros/config.json")
+    .option("-p, --profile <name>", "profile name (defaults to the workspace id)")
+    .option("--set-default", "also point the \"default\" profile at this workspace", false)
+    .option("--force", "replace an existing default profile without asking", false)
+    .option("--api-key <key>", "API key (otherwise prompted)")
+    .option("--workspace <id>", "workspace id (otherwise prompted, unless --admin)")
+    .option("--admin", "admin key login — verify cross-workspace, no workspace required", false)
+    .option("--base-url <url>", "agent-api base URL", DEFAULTS.baseUrl)
+    .option("--as-agent <name>", "caller identity to send as agent_name", "advisoros-cli")
+    .option("--email <email>", "your email — recorded on the audit trail for every action")
+    .action(async (opts) => {
+      try {
+        let { apiKey, workspace, baseUrl, profile } = opts;
+        if (!apiKey) {
+          const r = await prompts({
+            type: "password",
+            name: "v",
+            message: "API key (from Settings → API Keys; advos_admin_… for admin)",
+            validate: (v) => v && v.length > 10 ? true : "Required",
+          });
+          apiKey = r.v;
+        }
+        if (!apiKey) return fail(new Error("Aborted"));
+
+        const isAdmin = opts.admin || apiKey.startsWith("advos_admin_");
+
+        if (!isAdmin && !workspace) {
+          const r = await prompts({
+            type: "text",
+            name: "v",
+            message: "Workspace ID (6-char slug, e.g. dmw9wj)",
+            validate: (v) => v && v.length >= 3 ? true : "Required",
+          });
+          workspace = r.v;
+        }
+        if (!isAdmin && !workspace) return fail(new Error("Aborted"));
+
+        const agentName = opts.asAgent || "advisoros-cli";
+
+        if (isAdmin) {
+          // Verify the admin key cross-workspace; no workspace slug needed.
+          const verify = await call("workspaces", "list", { limit: 1000 }, {
+            apiKey, baseUrl, agentName,
+          });
+          const count = verify?.pagination?.total ?? verify?.workspaces?.length ?? 0;
+          const adminData = { apiKey, baseUrl, admin: true, agentName, ...(opts.email ? { email: opts.email } : {}), ...(workspace ? { workspaceId: workspace } : {}) };
+          const adminName = profile || "admin";
+          const adminWrites = { [adminName]: adminData };
+          if (adminName !== "default" && (opts.setDefault || !(await getProfile("default")))) {
+            const okDefault = await confirmDefaultReplacement(workspace || "(admin)", opts);
+            if (okDefault) adminWrites.default = adminData;
+          }
+          await setProfiles(adminWrites, adminName);
+          profile = adminName;
+          process.stdout.write(chalk.green(
+            `\n✓ Logged in as admin profile "${profile}" — ${count} workspaces reachable\n` +
+            `  Config: ${CONFIG_PATH}\n` +
+            `  Tip: pass --workspace <slug> per command, or set ADVISOROS_WORKSPACE_ID.\n`,
+          ));
+          return;
+        }
+
+        // Verify the credentials with a cheap round-trip.
+        const verify = await call("agents", "list", {}, {
+          apiKey, workspaceId: workspace, baseUrl, agentName,
+        });
+        const count = verify?.agents?.length ?? 0;
+        // Named workspace profiles: without -p, the profile is named after the
+        // workspace so a second login can never silently overwrite the first.
+        const profileName = profile || workspace;
+        const data = { apiKey, workspaceId: workspace, baseUrl, agentName, ...(opts.email ? { email: opts.email } : {}) };
+        const writes = { [profileName]: data };
+
+        let defaultNote = "";
+        if (profileName !== "default") {
+          const existingDefault = await getProfile("default");
+          if (!existingDefault) {
+            writes.default = data;
+            defaultNote = `  Default profile set to workspace ${workspace}.\n`;
+          } else if (existingDefault.workspaceId === workspace) {
+            writes.default = data;
+          } else if (opts.setDefault || opts.force) {
+            const ok = await confirmDefaultReplacement(workspace, opts, existingDefault.workspaceId);
+            if (ok) {
+              writes.default = data;
+              defaultNote = `  Default profile moved from ${existingDefault.workspaceId} to ${workspace}.\n`;
+            } else {
+              defaultNote = `  Default profile left on workspace ${existingDefault.workspaceId}.\n`;
+            }
+          } else {
+            defaultNote =
+              `  Default profile still points at workspace ${existingDefault.workspaceId} — unchanged.\n` +
+              `  Use this workspace with: --profile ${profileName}   (or re-run login with --set-default)\n`;
+          }
+        }
+
+        await setProfiles(writes, profileName);
+        process.stdout.write(chalk.green(
+          `\n✓ Logged in as profile "${profileName}" — workspace ${workspace} (${count} agents visible)\n` +
+          `  Config: ${CONFIG_PATH}\n`,
+        ) + chalk.gray(defaultNote));
+      } catch (e) { fail(e); }
+    });
+
+  program
+    .command("whoami")
+    .description("Show the active profile and workspace")
+    .option("-p, --profile <name>", "profile name", "default")
+    .action(async (opts) => {
+      try {
+        const p = await getProfile(opts.profile);
+        if (!p) return fail(new Error(`Profile "${opts.profile}" not found. Run \`advisoros login\`.`));
+        const masked = p.apiKey ? p.apiKey.slice(0, 8) + "…" + p.apiKey.slice(-4) : "(none)";
+        const isAdmin = Boolean(p.admin) || String(p.apiKey || "").startsWith("advos_admin_");
+
+        let reachable = null;
+        if (isAdmin) {
+          try {
+            const r = await call("workspaces", "list", { limit: 1000 }, {
+              apiKey: p.apiKey, baseUrl: p.baseUrl, agentName: p.agentName,
+            });
+            reachable = r?.pagination?.total ?? r?.workspaces?.length ?? null;
+          } catch { reachable = null; }
+        }
+
+        process.stdout.write(
+          `profile:    ${opts.profile}\n` +
+          `scope:      ${isAdmin ? "admin (cross-workspace)" : "workspace"}\n` +
+          `workspace:  ${p.workspaceId || "(none — pass --workspace per command)"}\n` +
+          (isAdmin ? `reachable:  ${reachable == null ? "(could not verify)" : `${reachable} workspaces`}\n` : "") +
+          `agent:      ${p.agentName || "advisoros-cli"}\n` +
+          `base url:   ${p.baseUrl || DEFAULTS.baseUrl}\n` +
+          `api key:    ${masked}\n`,
+        );
+      } catch (e) { fail(e); }
+    });
+
+  program
+    .command("profiles")
+    .description("List saved profiles")
+    .action(async () => {
+      const profiles = await allProfiles();
+      const names = Object.keys(profiles);
+      if (!names.length) return process.stdout.write("(no profiles — run `advisoros login`)\n");
+      for (const name of names) {
+        const p = profiles[name];
+        const scope = p?.admin ? "admin" : (p?.workspaceId || "(no workspace)");
+        process.stdout.write(`- ${name}  →  ${scope}\n`);
+      }
+    });
+
+  program
+    .command("logout")
+    .description("Remove a saved profile")
+    .option("-p, --profile <name>", "profile name", "default")
+    .action(async (opts) => {
+      const ok = await deleteProfile(opts.profile);
+      process.stdout.write(ok ? chalk.green(`✓ Removed profile "${opts.profile}"\n`) : `(no profile "${opts.profile}")\n`);
+    });
+}

package/src/commands/brand.mjs

@@ -0,0 +1,439 @@
+import { call } from "../api.mjs";
+import { emit, fail, ctxFrom, withCommonOpts, confirmDestructive } from "../ui.mjs";
+
+const list = (v) => (v ? String(v).split(",").map((s) => s.trim()).filter(Boolean) : undefined);
+
+function collectFields(o) {
+  const body = {};
+  const text = {
+    primary: "primary_color", secondary: "secondary_color", accent: "accent_color",
+    ctaColor: "cta_color", ctaTextColor: "cta_text_color",
+    fontHeading: "font_heading", fontBody: "font_body", tone: "tone",
+    tagline: "tagline", notes: "notes",
+    logo: "logo_url", logoFull: "logo_full_url", logoFullDark: "logo_full_dark_url",
+    logoIconLight: "logo_icon_light_url", logoIconDark: "logo_icon_dark_url",
+    videoCtaType: "video_default_cta_type", videoCtaLabel: "video_default_cta_label",
+    videoCtaUrl: "video_default_cta_url", videoIntro: "video_intro_text",
+    videoShareDomain: "video_share_domain",
+  };
+  for (const [opt, field] of Object.entries(text)) if (o[opt] !== undefined) body[field] = o[opt];
+  if (o.extraColors !== undefined) body.extra_colors = list(o.extraColors) ?? [];
+  return body;
+}
+
+function printBrand(b) {
+  if (!b) return process.stdout.write("No brand record for this workspace yet.\n");
+  process.stdout.write(
+    `Colours:   primary ${b.primary_color || "-"}  secondary ${b.secondary_color || "-"}  accent ${b.accent_color || "-"}\n` +
+      `CTA:       ${b.cta_color || "-"} on ${b.cta_text_color || "-"}\n` +
+      `Fonts:     heading ${b.font_heading || "-"}  body ${b.font_body || "-"}\n` +
+      `Tone:      ${b.tone || "-"}\n` +
+      `Tagline:   ${b.tagline || "-"}\n` +
+      `Logos:     ${[b.logo_url, b.logo_full_url, b.logo_full_dark_url, b.logo_icon_light_url, b.logo_icon_dark_url].filter(Boolean).length} set\n` +
+      `Imagery:   style ${b.imagery_style || "-"} | mood ${b.imagery_mood || "-"}\n` +
+      `  motifs:  ${(b.imagery_motifs || []).join(", ") || "-"}\n` +
+      `  avoid:   ${b.imagery_avoid || "-"}\n` +
+      `  refs:    ${(b.imagery_reference_urls || []).join(", ") || "-"}\n` +
+      `Voice:     ${b.tone_of_voice_directive ? `${String(b.tone_of_voice_directive).slice(0, 120)}${String(b.tone_of_voice_directive).length > 120 ? "…" : ""}` : "-"}\n` +
+      `  source:  ${b.tone_of_voice_source || "-"}${b.tone_of_voice_synced_at ? ` (synced ${b.tone_of_voice_synced_at})` : ""}\n` +
+      `Video:     cta ${b.video_default_cta_type || "-"}${b.video_default_cta_label ? ` "${b.video_default_cta_label}"` : ""} | domain ${b.video_share_domain || "-"}\n` +
+      `Social:    ${Object.entries(b.reference_library || {}).filter(([k, v]) => k.startsWith("social_") && v).map(([k]) => k.replace(/^social_|_url$/g, "")).join(", ") || "-"}\n` +
+      (b.notes ? `Notes:     ${b.notes}\n` : ""),
+  );
+}
+
+function printImagery(i) {
+  process.stdout.write(
+    `Style:  ${i.imagery_style || "-"}\nMood:   ${i.imagery_mood || "-"}\n` +
+      `Motifs: ${(i.imagery_motifs || []).join(", ") || "-"}\n` +
+      `Avoid:  ${i.imagery_avoid || "-"}\nRefs:   ${(i.imagery_reference_urls || []).join(", ") || "-"}\n`,
+  );
+}
+
+export function registerBrand(program) {
+  const b = program
+    .command("brand")
+    .description("Read and edit the workspace brand: colours, fonts, logos, tagline and imagery direction");
+
+  withCommonOpts(b.command("show"))
+    .alias("get")
+    .description("Show the workspace brand record")
+    .action(async function () {
+      try {
+        const r = await call("brand", "get", {}, ctxFrom(this));
+        emit(this, r, (d) => printBrand(d.brand));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(b.command("set"))
+    .alias("update")
+    .description("Update any brand field (only the flags you pass are changed)")
+    .option("--primary <hex>", "primary colour")
+    .option("--secondary <hex>", "secondary colour")
+    .option("--accent <hex>", "accent colour")
+    .option("--extra-colors <list>", "comma-separated extra colours")
+    .option("--cta-color <hex>", "CTA background colour")
+    .option("--cta-text-color <hex>", "CTA text colour")
+    .option("--font-heading <name>", "heading font")
+    .option("--font-body <name>", "body font")
+    .option("--tone <tone>", "brand tone keyword")
+    .option("--tagline <text>", "tagline")
+    .option("--notes <text>", "brand notes")
+    .option("--logo <url>", "primary logo URL")
+    .option("--logo-full <url>", "full logo URL")
+    .option("--logo-full-dark <url>", "full logo (dark) URL")
+    .option("--logo-icon-light <url>", "icon logo (light) URL")
+    .option("--logo-icon-dark <url>", "icon logo (dark) URL")
+    .option("--video-cta-type <type>", "default video CTA type")
+    .option("--video-cta-label <text>", "default video CTA label")
+    .option("--video-cta-url <url>", "default video CTA URL")
+    .option("--video-intro <text>", "default video intro text")
+    .option("--video-share-domain <domain>", "video share domain")
+    .action(async function (o) {
+      try {
+        const body = collectFields(o);
+        if (!Object.keys(body).length) fail(new Error("Pass at least one field to update."));
+        const r = await call("brand", "update", body, ctxFrom(this));
+        emit(this, r, (d) => { process.stdout.write(`Updated: ${(d.updated || []).join(", ")}\n\n`); printBrand(d.brand); });
+      } catch (e) { fail(e); }
+    });
+
+  // ── imagery direction ──────────────────────────────────────────────────
+  const img = b.command("imagery").description("Manage the imagery direction used for every generated image");
+
+  withCommonOpts(img.command("show"))
+    .alias("get")
+    .description("Show the imagery direction")
+    .action(async function () {
+      try {
+        const r = await call("brand", "imagery", {}, ctxFrom(this));
+        emit(this, r, (d) => printImagery(d.imagery || {}));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(img.command("set"))
+    .alias("update")
+    .description("Set imagery style, motifs, mood, avoid list or reference URLs")
+    .option("--style <text>", "imagery style")
+    .option("--mood <text>", "imagery mood")
+    .option("--avoid <text>", "what to avoid")
+    .option("--motifs <list>", "comma-separated motifs (replaces the list)")
+    .option("--refs <list>", "comma-separated reference URLs (replaces the list)")
+    .action(async function (o) {
+      try {
+        const body = {};
+        if (o.style !== undefined) body.imagery_style = o.style;
+        if (o.mood !== undefined) body.imagery_mood = o.mood;
+        if (o.avoid !== undefined) body.imagery_avoid = o.avoid;
+        if (o.motifs !== undefined) body.imagery_motifs = list(o.motifs) ?? [];
+        if (o.refs !== undefined) body.imagery_reference_urls = list(o.refs) ?? [];
+        if (!Object.keys(body).length) fail(new Error("Pass at least one imagery field."));
+        const r = await call("brand", "set_imagery", body, ctxFrom(this));
+        emit(this, r, (d) => printImagery(d.imagery || {}));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(img.command("add-motifs <motifs>"))
+    .description("Add motifs (comma-separated) without replacing existing ones")
+    .action(async function (m) {
+      try {
+        const r = await call("brand", "add_motifs", { motifs: list(m) }, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(`Motifs: ${(d.imagery_motifs || []).join(", ") || "-"}\n`));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(img.command("remove-motifs <motifs>"))
+    .description("Remove motifs (comma-separated)")
+    .action(async function (m) {
+      try {
+        const r = await call("brand", "remove_motifs", { motifs: list(m) }, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(`Motifs: ${(d.imagery_motifs || []).join(", ") || "-"}\n`));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(img.command("add-refs <urls>"))
+    .description("Add reference URLs (comma-separated)")
+    .action(async function (u) {
+      try {
+        const r = await call("brand", "add_reference_urls", { urls: list(u) }, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(`Refs: ${(d.imagery_reference_urls || []).join(", ") || "-"}\n`));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(img.command("remove-refs <urls>"))
+    .description("Remove reference URLs (comma-separated)")
+    .action(async function (u) {
+      try {
+        const r = await call("brand", "remove_reference_urls", { urls: list(u) }, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(`Refs: ${(d.imagery_reference_urls || []).join(", ") || "-"}\n`));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(img.command("clear"))
+    .description("Clear the imagery direction (or only --fields style,motifs...)")
+    .option("--fields <list>", "comma-separated imagery fields to clear")
+    .action(async function (o) {
+      try {
+        await confirmDestructive(this, "Clear the workspace imagery direction.");
+        const fields = list(o.fields)?.map((f) => (f.startsWith("imagery_") ? f : `imagery_${f}`));
+        const r = await call("brand", "clear_imagery", fields ? { fields } : {}, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(`Cleared: ${(d.cleared || []).join(", ")}\n`));
+      } catch (e) { fail(e); }
+    });
+
+  // ── logos ──────────────────────────────────────────────────────────────
+  const printLogos = (l = {}) =>
+    process.stdout.write(
+      `Primary:    ${l.logo_url || "-"}\nFull:       ${l.logo_full_url || "-"}\n` +
+        `Full dark:  ${l.logo_full_dark_url || "-"}\nIcon light: ${l.logo_icon_light_url || "-"}\n` +
+        `Icon dark:  ${l.logo_icon_dark_url || "-"}\n`,
+    );
+
+  const lg = b.command("logos").alias("logo").description("Manage the workspace logo files and URLs");
+
+  withCommonOpts(lg.command("show"))
+    .alias("get")
+    .description("Show every logo variant")
+    .action(async function () {
+      try {
+        const r = await call("brand", "logos", {}, ctxFrom(this));
+        emit(this, r, (d) => printLogos(d.logos || {}));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(lg.command("set <variant> <url>"))
+    .description("Point a logo variant (full, full_dark, icon_light, icon_dark, primary) at a URL")
+    .action(async function (variant, url) {
+      try {
+        const r = await call("brand", "set_logos", { variant, url }, ctxFrom(this));
+        emit(this, r, (d) => printLogos(d.logos || {}));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(lg.command("upload <file>"))
+    .description("Upload a logo image file and store it against a variant")
+    .option("--variant <variant>", "full, full_dark, icon_light, icon_dark or primary", "full")
+    .action(async function (file, o) {
+      try {
+        const { readFile } = await import("node:fs/promises");
+        const path = await import("node:path");
+        const buf = await readFile(file);
+        if (buf.byteLength > 5 * 1024 * 1024) fail(new Error("Logo must be under 5 MB."));
+        const body = {
+          variant: o.variant,
+          filename: path.basename(file),
+          data: buf.toString("base64"),
+        };
+        const r = await call("brand", "upload_logo", body, ctxFrom(this));
+        emit(this, r, (d) => {
+          process.stdout.write(`Uploaded ${d.uploaded?.variant}: ${d.uploaded?.url}\n\n`);
+          printLogos(d.logos || {});
+        });
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(lg.command("clear"))
+    .description("Remove all logos, or only --variants full,icon_dark")
+    .option("--variants <list>", "comma-separated variants to clear")
+    .action(async function (o) {
+      try {
+        await confirmDestructive(this, "Clear the workspace logos.");
+        const variants = list(o.variants);
+        const r = await call("brand", "clear_logos", variants ? { variants } : {}, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(`Cleared: ${(d.cleared || []).join(", ")}\n`));
+      } catch (e) { fail(e); }
+    });
+
+  // ── social links ───────────────────────────────────────────────────────
+  const NETWORKS = ["linkedin", "twitter", "facebook", "instagram", "youtube", "tiktok", "threads", "github"];
+  const printSocial = (s = {}) =>
+    process.stdout.write(NETWORKS.map((n) => `${(n + ":").padEnd(11)}${s[n] || "-"}`).join("\n") + "\n");
+
+  const so = b.command("social").description("Manage the brand's social profile links");
+
+  withCommonOpts(so.command("show"))
+    .alias("get")
+    .description("Show the social profile links")
+    .action(async function () {
+      try {
+        const r = await call("brand", "social", {}, ctxFrom(this));
+        emit(this, r, (d) => printSocial(d.social || {}));
+      } catch (e) { fail(e); }
+    });
+
+  const soSet = withCommonOpts(so.command("set"))
+    .alias("update")
+    .description("Set one or more social profile links");
+  for (const n of NETWORKS) soSet.option(`--${n} <url>`, `${n} profile URL`);
+  soSet.action(async function (o) {
+    try {
+      const body = {};
+      for (const n of NETWORKS) if (o[n] !== undefined) body[n] = o[n];
+      if (!Object.keys(body).length) fail(new Error(`Pass at least one of: ${NETWORKS.map((n) => `--${n}`).join(", ")}.`));
+      const r = await call("brand", "set_social", body, ctxFrom(this));
+      emit(this, r, (d) => printSocial(d.social || {}));
+    } catch (e) { fail(e); }
+  });
+
+  withCommonOpts(so.command("clear"))
+    .description("Remove all social links, or only --networks linkedin,github")
+    .option("--networks <list>", "comma-separated networks to clear")
+    .action(async function (o) {
+      try {
+        await confirmDestructive(this, "Clear the workspace social links.");
+        const networks = list(o.networks);
+        const r = await call("brand", "clear_social", networks ? { networks } : {}, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(`Cleared: ${(d.cleared || []).join(", ")}\n`));
+      } catch (e) { fail(e); }
+    });
+
+  // ── video share branding ───────────────────────────────────────────────
+  const printVideo = (v = {}) =>
+    process.stdout.write(
+      `CTA type:   ${v.video_default_cta_type || "-"}\nCTA label:  ${v.video_default_cta_label || "-"}\n` +
+        `CTA URL:    ${v.video_default_cta_url || "-"}\nIntro text: ${v.video_intro_text || "-"}\n` +
+        `Share domain: ${v.video_share_domain || "-"}\n`,
+    );
+
+  const vd = b.command("video").description("Manage the branded video share page defaults");
+
+  withCommonOpts(vd.command("show"))
+    .alias("get")
+    .description("Show the video share branding defaults")
+    .action(async function () {
+      try {
+        const r = await call("brand", "video", {}, ctxFrom(this));
+        emit(this, r, (d) => printVideo(d.video || {}));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(vd.command("set"))
+    .alias("update")
+    .description("Set the default video CTA, intro text or share domain")
+    .option("--cta-type <type>", "default CTA type (e.g. booking, website, none)")
+    .option("--cta-label <text>", "button label")
+    .option("--cta-url <url>", "CTA destination URL")
+    .option("--intro <text>", "intro text shown on the share page")
+    .option("--share-domain <domain>", "custom share domain")
+    .action(async function (o) {
+      try {
+        const body = {};
+        if (o.ctaType !== undefined) body.video_default_cta_type = o.ctaType;
+        if (o.ctaLabel !== undefined) body.video_default_cta_label = o.ctaLabel;
+        if (o.ctaUrl !== undefined) body.video_default_cta_url = o.ctaUrl;
+        if (o.intro !== undefined) body.video_intro_text = o.intro;
+        if (o.shareDomain !== undefined) body.video_share_domain = o.shareDomain;
+        if (!Object.keys(body).length) fail(new Error("Pass at least one video field."));
+        const r = await call("brand", "set_video", body, ctxFrom(this));
+        emit(this, r, (d) => printVideo(d.video || {}));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(vd.command("clear"))
+    .description("Clear the video share defaults (or only --fields cta_url,intro_text)")
+    .option("--fields <list>", "comma-separated video fields to clear")
+    .action(async function (o) {
+      try {
+        await confirmDestructive(this, "Clear the video share branding defaults.");
+        const fields = list(o.fields)?.map((f) => (f.startsWith("video_") ? f : `video_${f}`));
+        const r = await call("brand", "clear_video", fields ? { fields } : {}, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(`Cleared: ${(d.cleared || []).join(", ")}\n`));
+      } catch (e) { fail(e); }
+    });
+
+  // ── tone of voice ──────────────────────────────────────────────────────
+
+  const tv = b.command("tone").description("Manage the tone of voice directive used when writing copy");
+
+  const printTone = (t = {}) =>
+    process.stdout.write(
+      `Keyword:   ${t.tone || "-"}\nDirective: ${t.directive || "-"}\n` +
+        `Source:    ${t.source || "-"}\nSynced:    ${t.synced_at || "-"}\n` +
+        (t.apply_by_default === undefined ? "" : `Applied by default: ${t.apply_by_default ? "yes" : "no"}\n`),
+    );
+
+  withCommonOpts(tv.command("show"))
+    .alias("get")
+    .description("Show the tone of voice directive")
+    .action(async function () {
+      try {
+        const r = await call("brand", "tone", {}, ctxFrom(this));
+        emit(this, r, (d) => printTone(d.tone || {}));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(tv.command("set"))
+    .alias("update")
+    .description("Set the tone of voice directive (and optional keyword/source)")
+    .option("--directive <text>", "the tone of voice directive")
+    .option("--file <path>", "read the directive from a file")
+    .option("--source <name>", "where it came from (default: manual)")
+    .option("--keyword <tone>", "short brand tone keyword")
+    .action(async function (o) {
+      try {
+        const body = {};
+        if (o.file) body.directive = await (await import("node:fs/promises")).readFile(o.file, "utf8");
+        if (o.directive !== undefined) body.directive = o.directive;
+        if (o.source !== undefined) body.source = o.source;
+        if (o.keyword !== undefined) body.tone = o.keyword;
+        if (!Object.keys(body).length) fail(new Error("Pass --directive, --file or --keyword."));
+        const r = await call("brand", "set_tone", body, ctxFrom(this));
+        emit(this, r, (d) => printTone(d.tone || {}));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(tv.command("clear"))
+    .description("Remove the tone of voice directive")
+    .action(async function () {
+      try {
+        await confirmDestructive(this, "Clear this workspace's tone of voice directive.");
+        const r = await call("brand", "clear_tone", {}, ctxFrom(this));
+        emit(this, r, () => process.stdout.write("Tone of voice cleared.\n"));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(tv.command("apply <on|off>"))
+    .description("Apply the tone of voice by default when generating content")
+    .action(async function (v) {
+      try {
+        const enabled = ["on", "true", "yes", "1"].includes(String(v).toLowerCase());
+        const r = await call("brand", "set_tone_default", { apply_by_default: enabled }, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(`Applied by default: ${d.apply_by_default ? "yes" : "no"}\n`));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(tv.command("sync"))
+    .description("Pull the latest tone of voice from Business Build")
+    .option("--email <email>", "client identity email to resolve against")
+    .action(async function (o) {
+      try {
+        const r = await call("brand", "sync_tone", o.email ? { email: o.email } : {}, ctxFrom(this));
+        emit(this, r, (d) => printTone(d.tone || {}));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(b.command("delete"))
+    .alias("reset")
+    .description("Delete the entire brand record for this workspace")
+    .action(async function () {
+      try {
+        await confirmDestructive(this, "Delete this workspace's whole brand record.");
+        const r = await call("brand", "delete", {}, ctxFrom(this));
+        emit(this, r, () => process.stdout.write("Brand record deleted.\n"));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(b.command("fields"))
+    .description("List every editable brand field")
+    .action(async function () {
+      try {
+        const r = await call("brand", "fields", {}, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(
+          `Text: ${(d.text_fields || []).join(", ")}\nLists: ${(d.list_fields || []).join(", ")}\n` +
+            `Imagery: ${(d.imagery_fields || []).join(", ")}\nTone: ${(d.tone_fields || []).join(", ")}\n` +
+            `Logos: ${(d.logo_fields || []).join(", ")}\nLogo variants: ${(d.logo_variants || []).join(", ")}\n` +
+            `Video: ${(d.video_fields || []).join(", ")}\nSocial: ${(d.social_networks || []).join(", ")}\n`,
+        ));
+      } catch (e) { fail(e); }
+    });
+}