@series-a/cli 0.7.1 → 0.15.1

package/src/commands/resources.mjs

@@ -1049,11 +1049,27 @@ export function registerContent(program) {
     });
 
   withCommonOpts(c.command("schedule <id> <isoTimestamp>"))
-    .description("Schedule a content item")
-    .action(async function (id, ts) {
+    .description("Schedule a content item (Taplio when connected, otherwise built-in cron)")
+    .option("--channel <c>", "linkedin | blog | newsletter")
+    .option("--publish-as <p>", "personal | company")
+    .option("--company-page <id>", "company page id when publishing as company")
+    .option("--timezone <tz>", "IANA timezone label to store")
+    .action(async function (id, ts, opts) {
+      try {
+        const r = await call("content", "schedule", {
+          id, scheduled_for: ts, channel: opts.channel,
+          publish_as: opts.publishAs, company_page_id: opts.companyPage, timezone: opts.timezone,
+        }, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(`✓ Scheduled via ${d.engine} for ${d.scheduled_for}\n`));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(c.command("unschedule <id>"))
+    .description("Cancel a scheduled content item on whichever engine holds it")
+    .action(async function (id) {
       try {
-        const r = await call("content", "schedule", { id, scheduled_date: ts }, ctxFrom(this));
-        emit(this, r, (d) => process.stdout.write(`✓ Scheduled ${d.content?.id} → ${d.content?.scheduled_date}\n`));
+        const r = await call("content", "unschedule", { id }, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(`✓ Unscheduled ${d.unscheduled ?? id}${d.engine ? ` (${d.engine})` : ""}\n`));
       } catch (e) { fail(e); }
     });
 
@@ -1066,15 +1082,58 @@ export function registerContent(program) {
       } catch (e) { fail(e); }
     });
 
+  withCommonOpts(c.command("bulk-approve [ids...]"))
+    .description("Approve many content items (all pending when no ids given)")
+    .option("--campaign <id>", "only pending items in this campaign")
+    .option("-y, --yes", "skip the confirmation prompt")
+    .action(async function (ids, opts) {
+      try {
+        if (!ids?.length) await confirmDestructive(this, "Approve every pending content item in this workspace.");
+        const r = await call("content", "bulk_approve", {
+          ids: ids?.length ? ids : undefined, campaign_id: opts.campaign,
+        }, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(`✓ Approved ${d.approved} items\n`));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(c.command("bulk-schedule <ids...>"))
+    .description("Schedule several content items on a cadence via the live engine")
+    .option("--start <iso>", "first slot (default: in 1 hour)")
+    .option("--interval-hours <n>", "hours between posts", "24")
+    .option("--channel <c>", "linkedin | blog | newsletter")
+    .option("--publish-as <p>", "personal | company")
+    .action(async function (ids, opts) {
+      try {
+        const r = await call("content", "bulk_schedule", {
+          ids, start: opts.start, interval_hours: Number(opts.intervalHours),
+          channel: opts.channel, publish_as: opts.publishAs,
+        }, ctxFrom(this));
+        emit(this, r, (d) => {
+          process.stdout.write(table(
+            ["id", "ok", "engine", "when / error"],
+            (d.results || []).map((x) => [truncate(x.id, 8), x.ok ? "yes" : "no", x.engine ?? "—", x.scheduled_for ?? truncate(x.error ?? "", 50)]),
+          ) + `\n${d.scheduled} scheduled, ${d.failed} failed\n`);
+        });
+      } catch (e) { fail(e); }
+    });
+
   withCommonOpts(c.command("publish <id>"))
-    .description("Dispatch publication via agent-content-posting")
-    .action(async function (id) {
+    .description("Publish a content item immediately")
+    .option("--channel <c>", "linkedin | blog | newsletter")
+    .option("--publish-as <p>", "personal | company")
+    .option("--company-page <id>", "company page id when publishing as company")
+    .option("-y, --yes", "skip the confirmation prompt")
+    .action(async function (id, opts) {
       try {
-        const r = await call("content", "publish", { id }, ctxFrom(this));
-        emit(this, r, (d) => process.stdout.write(JSON.stringify(d.publish, null, 2) + "\n"));
+        await confirmDestructive(this, `Publish content item ${id} right now.`);
+        const r = await call("content", "publish_now", {
+          id, channel: opts.channel, publish_as: opts.publishAs, company_page_id: opts.companyPage,
+        }, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(`✓ Published via ${d.worker}\n`));
       } catch (e) { fail(e); }
     });
 
+
   withCommonOpts(c.command("delete <id>"))
     .description("Delete a content item")
     .option("-y, --yes", "skip the confirmation prompt")
@@ -1181,11 +1240,13 @@ export function registerCalendar(program) {
     .option("--cta <text>", "call to action")
     .option("--campaign <id>", "campaign_id")
     .option("--status <s>", "draft | scheduled | published", "draft")
+    .option("--at <iso>", "ISO timestamp — schedules the post immediately via the live engine")
     .action(async function (opts) {
       try {
         let content = opts.content;
         if (opts.contentFile) content = await readFile(opts.contentFile, "utf8");
         const r = await call("calendar", "create", {
+          scheduled_for: opts.at,
           title: opts.title, scheduled_date: opts.date, scheduled_time: opts.time,
           platform: opts.platform, content: content ?? "",
           hashtags: opts.hashtags ? opts.hashtags.split(",").map((s) => s.trim()) : undefined,
@@ -1221,17 +1282,99 @@ export function registerCalendar(program) {
     });
 
   withCommonOpts(cal.command("delete <id>"))
-    .description("Delete a calendar post")
+    .description("Delete a calendar post (cancels it on Taplio first when applicable)")
     .option("-y, --yes", "skip the confirmation prompt")
     .action(async function (id) {
       try {
         await confirmDestructive(this, `Delete calendar post ${id}. This cannot be undone.`);
         const r = await call("calendar", "delete", { id }, ctxFrom(this));
-        emit(this, r, (d) => process.stdout.write(`✓ Deleted ${d.deleted}\n`));
+        emit(this, r, (d) => process.stdout.write(`✓ Deleted ${d.deleted ?? d.unscheduled ?? id}\n`));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(cal.command("engine"))
+    .description("Show which scheduler is live for this workspace (Taplio or built-in cron)")
+    .option("--channel <c>", "linkedin | blog | newsletter", "linkedin")
+    .action(async function (opts) {
+      try {
+        const r = await call("calendar", "engine", { channel: opts.channel }, ctxFrom(this));
+        emit(this, r, (d) => {
+          process.stdout.write(
+            `Engine:            ${d.engine}\n` +
+            `Channel:           ${d.channel}\n` +
+            `Taplio connected:  ${d.taplio_connected ? "yes" : "no"}\n` +
+            `Dispatch worker:   ${d.dispatch_worker}\n` +
+            `Reason:            ${d.reason}\n` +
+            `Pending scheduled: ${d.scheduled_pending}\n` +
+            (d.recent_failures?.length
+              ? `\nRecent failures:\n` + table(
+                ["id", "when", "attempts", "error"],
+                d.recent_failures.map((f) => [truncate(f.id, 8), f.scheduled_for ?? "—", f.dispatch_attempts ?? 0, truncate(f.dispatch_error ?? "", 60)]),
+              ) + "\n"
+              : ""),
+          );
+        });
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(cal.command("schedule <id>"))
+    .description("Schedule (or reschedule) a calendar post via the live engine")
+    .requiredOption("--at <iso>", "ISO timestamp, e.g. 2026-09-10T09:00:00Z")
+    .option("--channel <c>", "linkedin | blog | newsletter")
+    .option("--publish-as <p>", "personal | company")
+    .option("--company-page <id>", "company page id when publishing as company")
+    .option("--timezone <tz>", "IANA timezone label to store")
+    .action(async function (id, opts) {
+      try {
+        const r = await call("calendar", "schedule", {
+          id, scheduled_for: opts.at, channel: opts.channel,
+          publish_as: opts.publishAs, company_page_id: opts.companyPage, timezone: opts.timezone,
+        }, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(`✓ Scheduled via ${d.engine} for ${d.scheduled_for}\n`));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(cal.command("unschedule <id>"))
+    .description("Cancel a scheduled calendar post (cancels on Taplio when it owns it)")
+    .action(async function (id) {
+      try {
+        const r = await call("calendar", "unschedule", { id }, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(`✓ Unscheduled ${d.unscheduled} (${d.engine})\n`));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(cal.command("publish-now <id>"))
+    .description("Publish a calendar post immediately")
+    .option("-y, --yes", "skip the confirmation prompt")
+    .action(async function (id) {
+      try {
+        await confirmDestructive(this, `Publish calendar post ${id} right now.`);
+        const r = await call("calendar", "publish_now", { id }, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(`✓ Published via ${d.worker}\n`));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(cal.command("bulk-schedule <ids...>"))
+    .description("Schedule several calendar posts on a cadence")
+    .option("--start <iso>", "first slot (default: in 1 hour)")
+    .option("--interval-hours <n>", "hours between posts", "24")
+    .option("--channel <c>", "linkedin | blog | newsletter")
+    .action(async function (ids, opts) {
+      try {
+        const r = await call("calendar", "bulk_schedule", {
+          ids, start: opts.start, interval_hours: Number(opts.intervalHours), channel: opts.channel,
+        }, ctxFrom(this));
+        emit(this, r, (d) => {
+          process.stdout.write(table(
+            ["id", "ok", "engine", "when / error"],
+            (d.results || []).map((x) => [truncate(x.id, 8), x.ok ? "yes" : "no", x.engine ?? "—", x.scheduled_for ?? truncate(x.error ?? "", 50)]),
+          ) + `\n${d.scheduled} scheduled, ${d.failed} failed\n`);
+        });
       } catch (e) { fail(e); }
     });
 }
 
+
 export function registerSignals(program) {
   const s = program.command("signals").description("Read and manage market intelligence signals");
 

package/src/commands/strategies.mjs

@@ -0,0 +1,242 @@
+import { call } from "../api.mjs";
+import { emit, fail, ctxFrom, withCommonOpts, table, truncate, confirmDestructive } from "../ui.mjs";
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+export function registerStrategies(program) {
+  const s = program
+    .command("strategy")
+    .alias("strategies")
+    .description("Build and manage AI content strategies (multi-week content arcs)");
+
+  withCommonOpts(s.command("ideate"))
+    .description("Propose 3 grounded strategy directions from KB + signals")
+    .option("--hint <text>", "steer the ideation (theme, audience, launch…)")
+    .option("--no-tone", "do not apply the workspace tone of voice")
+    .action(async function () {
+      try {
+        const o = this.optsWithGlobals();
+        const r = await call("strategies", "ideate", {
+          hint: o.hint, apply_tone_of_voice: o.tone !== false,
+        }, ctxFrom(this));
+        emit(this, r, (d) => {
+          (d.strategies || []).forEach((st, i) => {
+            process.stdout.write(
+              `\n${i + 1}. ${st.name}\n   audience: ${st.audience}\n   outcome:  ${st.outcome}\n   pillars:  ${(st.pillars || []).join(", ")}\n   ${st.narrative}\n`,
+            );
+          });
+          process.stdout.write("\n");
+        });
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(s.command("create"))
+    .description("Build a full strategy: plans the arc and queues every post for drafting")
+    .requiredOption("--name <name>", "strategy name")
+    .option("--narrative <text>", "the story arc")
+    .option("--audience <text>", "who it targets")
+    .option("--outcome <text>", "what it should achieve")
+    .option("--pillars <list>", "comma-separated content pillars")
+    .option("--months <n>", "duration in months", "1")
+    .option("--per-week <n>", "posts per week (1-5)", "3")
+    .option("--format <f>", "linkedin | blog | mixed", "linkedin")
+    .option("--no-tone", "do not apply the workspace tone of voice")
+    .option("--wait", "poll resume until every post is drafted")
+    .action(async function (opts) {
+      try {
+        const ctx = ctxFrom(this);
+        const r = await call("strategies", "create", {
+          strategy: {
+            name: opts.name, narrative: opts.narrative, audience: opts.audience,
+            outcome: opts.outcome,
+            pillars: opts.pillars ? String(opts.pillars).split(",").map((p) => p.trim()) : [],
+          },
+          duration_months: Number(opts.months),
+          posts_per_week: Number(opts.perWeek),
+          format_mix: opts.format,
+          apply_tone_of_voice: opts.tone !== false,
+        }, ctx);
+        const id = r?.data?.strategy?.id ?? r?.strategy?.id;
+        if (opts.wait && id) {
+          for (let i = 0; i < 90; i++) {
+            await sleep(8000);
+            const p = await call("strategies", "resume", { id }, ctx);
+            const d = p?.data ?? p;
+            process.stderr.write(`  … ${d.progress?.done ?? 0}/${d.progress?.total ?? "?"} done\n`);
+            if (d.status === "ready" || d.status === "failed") break;
+          }
+          const final = await call("strategies", "get", { id, include_posts: false }, ctx);
+          return emit(this, final, (d) => process.stdout.write(`✓ ${d.strategy?.name} — ${d.strategy?.status}\n`));
+        }
+        emit(this, r, (d) => process.stdout.write(
+          `✓ Created strategy ${d.strategy?.id} (${d.total_posts ?? "?"} posts queued)\n  Run: advisoros strategy resume ${d.strategy?.id}\n`,
+        ));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(s.command("list"))
+    .description("List content strategies")
+    .option("--status <s>", "planning | generating | ready | failed | archived")
+    .option("--search <q>", "search by name")
+    .option("--limit <n>", "max rows", "25")
+    .action(async function () {
+      try {
+        const o = this.optsWithGlobals();
+        const r = await call("strategies", "list", {
+          status: o.status, search: o.search, limit: Number(o.limit),
+        }, ctxFrom(this));
+        emit(this, r, (d) => {
+          process.stdout.write(table(
+            ["id", "status", "posts", "wk", "name"],
+            (d.strategies || []).map((st) => [
+              truncate(st.id, 8), st.status, st.total_posts ?? "", st.posts_per_week ?? "",
+              truncate(st.name, 46),
+            ]),
+          ) + `\n${d.strategies?.length ?? 0} rows\n`);
+        });
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(s.command("show <id>"))
+    .description("Show a strategy with its planned posts")
+    .option("--no-posts", "omit the post list")
+    .action(async function (id, opts) {
+      try {
+        const r = await call("strategies", "get", { id, include_posts: opts.posts !== false }, ctxFrom(this));
+        emit(this, r, (d) => {
+          const st = d.strategy || {};
+          process.stdout.write(`${st.name}  [${st.status}]\n${st.narrative ?? ""}\n\n`);
+          if (d.posts?.length) {
+            process.stdout.write(table(
+              ["#", "wk", "status", "format", "date", "hook"],
+              d.posts.map((p) => [p.position, p.week_no, p.status, p.format, p.planned_date ?? "", truncate(p.hook, 44)]),
+            ) + "\n");
+          }
+          if (d.progress) process.stdout.write(`\n${JSON.stringify(d.progress)}\n`);
+        });
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(s.command("resume <id>"))
+    .description("Push the drafting queue along (repeat until status is ready)")
+    .option("--wait", "keep polling until done")
+    .action(async function (id, opts) {
+      try {
+        const ctx = ctxFrom(this);
+        let r = await call("strategies", "resume", { id }, ctx);
+        if (opts.wait) {
+          for (let i = 0; i < 90; i++) {
+            const d = r?.data ?? r;
+            if (d.status === "ready" || d.status === "failed") break;
+            process.stderr.write(`  … ${d.progress?.done ?? 0}/${d.progress?.total ?? "?"} done\n`);
+            await sleep(8000);
+            r = await call("strategies", "resume", { id }, ctx);
+          }
+        }
+        emit(this, r, (d) => process.stdout.write(`${d.status} — ${JSON.stringify(d.progress)}\n`));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(s.command("update <id>"))
+    .description("Patch a strategy")
+    .option("--name <n>")
+    .option("--narrative <text>")
+    .option("--audience <text>")
+    .option("--outcome <text>")
+    .option("--pillars <list>", "comma-separated")
+    .option("--status <s>", "planning | generating | ready | failed | archived")
+    .option("--campaign <id>", "link to a campaign")
+    .action(async function (id, opts) {
+      try {
+        const r = await call("strategies", "update", {
+          id, name: opts.name, narrative: opts.narrative, audience: opts.audience,
+          outcome: opts.outcome, status: opts.status, campaign_id: opts.campaign,
+          pillars: opts.pillars ? String(opts.pillars).split(",").map((p) => p.trim()) : undefined,
+        }, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(`✓ Updated ${d.strategy?.id}\n`));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(s.command("delete <id>"))
+    .description("Delete a strategy and its planned posts")
+    .option("-y, --yes", "skip the confirmation prompt")
+    .action(async function (id) {
+      try {
+        await confirmDestructive(this, `Delete strategy ${id} and every planned post. This cannot be undone.`);
+        const r = await call("strategies", "delete", { id }, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(`✓ Deleted ${d.deleted}\n`));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(s.command("posts <id>"))
+    .description("List the planned posts of a strategy")
+    .option("--status <s>", "queued | claimed | done | failed | skipped")
+    .option("--limit <n>", "max rows", "200")
+    .action(async function (id) {
+      try {
+        const o = this.optsWithGlobals();
+        const r = await call("strategies", "posts", { id, status: o.status, limit: Number(o.limit) }, ctxFrom(this));
+        emit(this, r, (d) => {
+          process.stdout.write(table(
+            ["post_id", "#", "wk", "status", "format", "date", "hook"],
+            (d.posts || []).map((p) => [
+              truncate(p.id, 8), p.position, p.week_no, p.status, p.format,
+              p.planned_date ?? "", truncate(p.hook, 38),
+            ]),
+          ) + `\n${JSON.stringify(d.progress)}\n`);
+        });
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(s.command("post <postId>"))
+    .description("Show one planned post")
+    .action(async function (postId) {
+      try {
+        const r = await call("strategies", "get_post", { post_id: postId }, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(JSON.stringify(d.post, null, 2) + "\n"));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(s.command("update-post <postId>"))
+    .description("Patch a planned post before it is drafted")
+    .option("--pillar <p>")
+    .option("--hook <text>")
+    .option("--objective <text>")
+    .option("--title <text>", "title_seed")
+    .option("--brief <text>")
+    .option("--format <f>", "linkedin | blog")
+    .option("--date <YYYY-MM-DD>", "planned_date")
+    .option("--week <n>", "week_no")
+    .option("--status <s>", "queued | claimed | done | failed | skipped")
+    .action(async function (postId, opts) {
+      try {
+        const r = await call("strategies", "update_post", {
+          post_id: postId, pillar: opts.pillar, hook: opts.hook, objective: opts.objective,
+          title_seed: opts.title, brief: opts.brief, format: opts.format,
+          planned_date: opts.date, week_no: opts.week ? Number(opts.week) : undefined,
+          status: opts.status,
+        }, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(`✓ Updated post ${d.post?.id}\n`));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(s.command("retry-post <postId>"))
+    .description("Re-queue a failed post for drafting")
+    .action(async function (postId) {
+      try {
+        const r = await call("strategies", "retry_post", { post_id: postId }, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(`✓ Re-queued ${d.post?.id}\n`));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(s.command("delete-post <postId>"))
+    .description("Remove a planned post")
+    .option("-y, --yes", "skip the confirmation prompt")
+    .action(async function (postId) {
+      try {
+        await confirmDestructive(this, `Delete planned post ${postId}.`);
+        const r = await call("strategies", "delete_post", { post_id: postId }, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(`✓ Deleted ${d.deleted}\n`));
+      } catch (e) { fail(e); }
+    });
+}

package/src/commands/voice.mjs

@@ -0,0 +1,202 @@
+import { call } from "../api.mjs";
+import { emit, fail, ctxFrom, withCommonOpts, table, truncate, confirmDestructive } from "../ui.mjs";
+
+export function registerVoice(program) {
+  const v = program
+    .command("voice")
+    .alias("tone")
+    .description("Read, write and delete the workspace Tone of Voice (directive, samples, scores)");
+
+  withCommonOpts(v.command("show"))
+    .alias("get")
+    .description("Show the workspace tone of voice configuration")
+    .action(async function () {
+      try {
+        const r = await call("voice", "get", {}, ctxFrom(this));
+        emit(this, r, (d) => {
+          const t = d.voice || {};
+          process.stdout.write(
+            `Directive: ${t.has_directive ? "set" : "(none)"}${t.source ? `  [source: ${t.source}]` : ""}\n` +
+              `Applied by default: ${t.apply_by_default ? "yes" : "no"}\n` +
+              `Writing samples: ${t.style_reference_count}${t.primary_style_reference_id ? `  (pinned: ${t.primary_style_reference_id})` : ""}\n` +
+              (t.synced_at ? `Last synced: ${t.synced_at}\n` : "") +
+              (t.directive ? `\n${t.directive}\n` : ""),
+          );
+        });
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(v.command("set"))
+    .description("Write the tone of voice directive and/or the apply-by-default toggle")
+    .option("--directive <text>", "the tone of voice directive")
+    .option("--source <text>", "where the directive came from", undefined)
+    .option("--apply-default <yes|no>", "apply tone of voice to new content by default")
+    .action(async function (opts) {
+      try {
+        const params = { directive: opts.directive, source: opts.source };
+        if (opts.applyDefault !== undefined) {
+          params.apply_by_default = /^(y|yes|true|1|on)$/i.test(String(opts.applyDefault));
+        }
+        const r = await call("voice", "set", params, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(
+          `✓ Tone of voice updated (directive ${d.voice?.has_directive ? "set" : "empty"}, default ${d.voice?.apply_by_default ? "on" : "off"})\n`,
+        ));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(v.command("delete"))
+    .alias("clear")
+    .description("Delete the tone of voice directive")
+    .option("--with-references", "also unmark every writing sample")
+    .option("-y, --yes", "skip the confirmation prompt")
+    .action(async function (opts) {
+      try {
+        await confirmDestructive(this, "Delete this workspace's tone of voice directive.");
+        const r = await call("voice", "delete", { clear_references: !!opts.withReferences }, ctxFrom(this));
+        emit(this, r, () => process.stdout.write("✓ Tone of voice cleared\n"));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(v.command("sync"))
+    .description("Re-pull the directive from Business Build")
+    .option("--email <email>", "identity to resolve the client by")
+    .action(async function (opts) {
+      try {
+        const r = await call("voice", "sync", { email: opts.email }, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(
+          `${d.voice?.has_directive ? "✓ Directive synced" : "No directive found"}\n`,
+        ));
+      } catch (e) { fail(e); }
+    });
+
+  // ── writing samples (benchmark corpus) ──
+  withCommonOpts(v.command("references"))
+    .alias("samples")
+    .description("List the knowledge base items used as writing samples")
+    .option("--limit <n>", "max rows", "50")
+    .action(async function (opts) {
+      try {
+        const r = await call("voice", "references", { limit: Number(opts.limit) }, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(
+          table(
+            ["id", "primary", "name", "category"],
+            (d.references || []).map((x) => [truncate(x.id, 8), x.is_primary ? "★" : "", truncate(x.name, 44), x.category ?? ""]),
+          ) + `\n${d.references?.length ?? 0} rows\n`,
+        ));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(v.command("add-reference <knowledgeItemId>"))
+    .description("Mark a knowledge base item as a writing sample")
+    .option("--primary", "also pin it as the benchmark sample")
+    .action(async function (id, opts) {
+      try {
+        const r = await call("voice", "add_reference", { knowledge_item_id: id, set_primary: !!opts.primary }, ctxFrom(this));
+        emit(this, r, () => process.stdout.write(`✓ ${id} is now a writing sample\n`));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(v.command("remove-reference <knowledgeItemId>"))
+    .description("Unmark a writing sample")
+    .action(async function (id) {
+      try {
+        const r = await call("voice", "remove_reference", { knowledge_item_id: id }, ctxFrom(this));
+        emit(this, r, () => process.stdout.write(`✓ ${id} removed from the writing samples\n`));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(v.command("set-primary [knowledgeItemId]"))
+    .description("Pin (or clear, when no id is given) the benchmark writing sample")
+    .action(async function (id) {
+      try {
+        const r = await call("voice", "set_primary", { knowledge_item_id: id ?? null }, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(
+          d.primary_style_reference_id ? `✓ Pinned ${d.primary_style_reference_id}\n` : "✓ Benchmark unpinned\n",
+        ));
+      } catch (e) { fail(e); }
+    });
+
+  // ── derived card + scoring ──
+  withCommonOpts(v.command("card"))
+    .description("Show the measured voice card (house rules + stylometric targets)")
+    .option("--rebuild", "rebuild it from the writing samples")
+    .action(async function (opts) {
+      try {
+        const r = await call("voice", "card", { rebuild: !!opts.rebuild }, ctxFrom(this));
+        emit(this, r, (d) => {
+          if (!d.card) return process.stdout.write("No voice card — add a writing sample first.\n");
+          process.stdout.write(
+            `Built: ${d.card.built_at}\nReferences: ${(d.card.reference_titles || []).join(", ")}\n\nRules:\n` +
+              (d.card.rules || []).map((x) => ` - ${x}`).join("\n") +
+              `\n\nTargets:\n` + (d.targets || []).map((x) => ` - ${x}`).join("\n") + "\n",
+          );
+        });
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(v.command("score"))
+    .description("Score a piece of writing against the workspace voice")
+    .option("--text <text>", "text to score")
+    .option("--content <id>", "content item to score")
+    .option("--reference <id>", "knowledge item to score against (defaults to the pinned sample)")
+    .option("--no-persist", "do not stamp the score onto the content item")
+    .action(async function (opts) {
+      try {
+        const r = await call("voice", "score", {
+          text: opts.text, content_item_id: opts.content,
+          reference_item_id: opts.reference, persist: opts.persist !== false,
+        }, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(
+          `Match: ${d.report?.overall_score ?? d.overall_score ?? "?"}%\n${d.report?.rationale ?? d.rationale ?? ""}\n`,
+        ));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(v.command("redraft"))
+    .description("Rewrite a piece in the author's voice (returns text, saves nothing)")
+    .option("--text <text>", "text to rewrite")
+    .option("--content <id>", "content item to rewrite")
+    .action(async function (opts) {
+      try {
+        const r = await call("voice", "redraft", { text: opts.text, content_item_id: opts.content }, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(`${d.text ?? d.redraft ?? JSON.stringify(d)}\n`));
+      } catch (e) { fail(e); }
+    });
+
+  // ── reports ──
+  withCommonOpts(v.command("reports"))
+    .description("List voice match reports")
+    .option("--content <id>", "only reports for this content item")
+    .option("--limit <n>", "max rows", "25")
+    .action(async function (opts) {
+      try {
+        const r = await call("voice", "reports", { content_item_id: opts.content, limit: Number(opts.limit) }, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(
+          table(
+            ["id", "score", "created", "subject"],
+            (d.reports || []).map((x) => [truncate(x.id, 8), x.overall_score, (x.created_at || "").slice(0, 16), truncate(x.subject_title, 40)]),
+          ) + `\n${d.reports?.length ?? 0} rows\n`,
+        ));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(v.command("report <id>"))
+    .description("Show one voice match report")
+    .action(async function (id) {
+      try {
+        const r = await call("voice", "get_report", { report_id: id }, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(JSON.stringify(d.report, null, 2) + "\n"));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(v.command("delete-report <id>"))
+    .description("Delete a voice match report")
+    .option("-y, --yes", "skip the confirmation prompt")
+    .action(async function (id) {
+      try {
+        await confirmDestructive(this, `Delete voice match report ${id}. This cannot be undone.`);
+        const r = await call("voice", "delete_report", { report_id: id }, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(`✓ Deleted ${d.deleted}\n`));
+      } catch (e) { fail(e); }
+    });
+}