@oppira/cli 0.1.0

package/src/commands/battlecard.js

@@ -0,0 +1,84 @@
+// battlecard: read latest/history (REST) + force-regenerate (local engine).
+import { apiRequest } from '../http.js';
+import { getCredentials } from '../config.js';
+import { withDb, findUserOrThrow, findCompetitorsForUser, backendImport } from '../local.js';
+import { resolveCompetitor } from './competitors.js';
+import { out, kv, table, info } from '../output.js';
+
+function opsEmail(ctx) {
+  const email = ctx.flag('email') || getCredentials(ctx.profileName).email;
+  if (!email) throw new Error('Provide --email (or log in) to select the target user.');
+  return email;
+}
+
+export default {
+  description: 'Battlecards — show, history, and force-regenerate (ops).',
+  commands: {
+    show: {
+      description: 'Show the current battlecard for a competitor.',
+      usage: 'battlecard show <name|id>',
+      async handler(ctx) {
+        const c = await resolveCompetitor(ctx.profileName, ctx.arg(0));
+        const res = await apiRequest(ctx.profileName, 'GET', `/battlecards/${c._id}`);
+        if (ctx.json) { out(res, ctx); return; }
+        const bc = res?.data || res?.battlecard || res;
+        if (!bc) { info('(no battlecard yet)'); return; }
+        kv({ competitor: c.name, generatedAt: bc.createdAt || bc.generatedAt || '—', version: bc.version || bc.generatorVersion || '—' }, ctx);
+        info('');
+        out(bc, { json: true });
+      },
+    },
+
+    history: {
+      description: 'List battlecard versions for a competitor.',
+      usage: 'battlecard history <name|id>',
+      async handler(ctx) {
+        const c = await resolveCompetitor(ctx.profileName, ctx.arg(0));
+        const res = await apiRequest(ctx.profileName, 'GET', `/battlecards/${c._id}/history`);
+        const versions = res?.data || res?.history || res || [];
+        if (ctx.json) { out(versions, ctx); return; }
+        const rows = (Array.isArray(versions) ? versions : []).map((v) => ({
+          id: String(v._id || v.battlecardId || '—'),
+          created: v.createdAt || '—',
+          version: v.version || v.generatorVersion || '—',
+        }));
+        table(rows, [{ key: 'id', label: 'ID' }, { key: 'created', label: 'CREATED' }, { key: 'version', label: 'VERSION' }], ctx);
+      },
+    },
+
+    regen: {
+      description: 'Force-regenerate a battlecard now (remote by default; --local runs the engine directly).',
+      usage: 'battlecard regen <name> [--local] [--email you@co.com]',
+      flags: [
+        { name: 'local', boolean: true, description: 'Run the engine directly (ops; needs repo + .env)' },
+        { name: 'email', description: 'Target user in --local mode (defaults to logged-in profile)' },
+      ],
+      async handler(ctx) {
+        const nameQuery = ctx.arg(0);
+        if (!nameQuery) throw new Error('Usage: oppira battlecard regen <competitor-name>');
+        if (!ctx.useLocal) {
+          // Remote: resolve the competitor id via the REST list, then hit the
+          // owner-scoped regenerate endpoint.
+          const c = await resolveCompetitor(ctx.profileName, nameQuery);
+          const res = await apiRequest(ctx.profileName, 'POST', `/battlecards/${c._id}/regenerate`, { body: {} });
+          if (ctx.json) { out(res, ctx); return; }
+          info(`✓ Battlecard regeneration triggered for "${c.name}".`);
+          if (res?.result) out(res.result, ctx);
+          return;
+        }
+        const email = opsEmail(ctx);
+        const result = await withDb(async () => {
+          const user = await findUserOrThrow(email);
+          const competitors = await findCompetitorsForUser(user, nameQuery);
+          if (competitors.length === 0) throw new Error(`No competitor matches "${nameQuery}" for ${email}.`);
+          if (competitors.length > 1) throw new Error(`Ambiguous: ${competitors.map((c) => c.name).join(', ')}.`);
+          const { generateBattlecard } = await backendImport('utils/battlecardGenerator.js');
+          return generateBattlecard({ user, competitor: competitors[0], force: true });
+        });
+        if (ctx.json) { out({ success: true, email, result }, ctx); return; }
+        info(`✓ Battlecard regeneration run for "${nameQuery}" (${email}, local).`);
+        if (result) out(result, ctx);
+      },
+    },
+  },
+};

package/src/commands/competitors.js

@@ -0,0 +1,276 @@
+// competitors (alias: comp): list / show / add / track / toggle / remove,
+// plus local-mode analytics (timeline / compare / top-posts / tone) that reuse
+// the MCP tool implementations directly against Mongo.
+import { apiRequest } from '../http.js';
+import { getCredentials } from '../config.js';
+import { withDb, findUserOrThrow, findCompetitorsForUser, backendImport } from '../local.js';
+import { out, kv, table, info } from '../output.js';
+
+// Resolve a single competitor for a user (local mode), returning the mongo _id.
+async function resolveLocalId(user, nameQuery) {
+  const competitors = await findCompetitorsForUser(user, nameQuery);
+  if (competitors.length === 0) throw new Error(`No competitor matches "${nameQuery}".`);
+  if (competitors.length > 1) throw new Error(`Ambiguous: ${competitors.map((c) => c.name).join(', ')}. Be more specific.`);
+  return { id: String(competitors[0]._id), name: competitors[0].name };
+}
+
+function opsEmail(ctx) {
+  const email = ctx.flag('email') || getCredentials(ctx.profileName).email;
+  if (!email) throw new Error('Provide --email (or log in) to select the target user.');
+  return email;
+}
+
+const isObjectId = (s) => typeof s === 'string' && /^[a-f0-9]{24}$/i.test(s);
+
+async function fetchCompetitors(profileName) {
+  const res = await apiRequest(profileName, 'GET', '/competitors');
+  return res?.data || res?.competitors || [];
+}
+
+// Accept an ObjectId directly, or resolve a (case-insensitive) name substring.
+async function resolveCompetitor(profileName, nameOrId) {
+  if (!nameOrId) throw new Error('A competitor name or id is required.');
+  const list = await fetchCompetitors(profileName);
+  if (isObjectId(nameOrId)) {
+    const byId = list.find((c) => String(c._id) === nameOrId);
+    return byId || { _id: nameOrId, name: '(unknown)' };
+  }
+  const q = nameOrId.toLowerCase();
+  const matches = list.filter((c) => (c.name || '').toLowerCase().includes(q));
+  if (matches.length === 0) throw new Error(`No tracked competitor matches "${nameOrId}".`);
+  if (matches.length > 1) {
+    throw new Error(`Ambiguous — "${nameOrId}" matches: ${matches.map((c) => c.name).join(', ')}. Use the id.`);
+  }
+  return matches[0];
+}
+
+const PLATFORM_FLAGS = [
+  ['facebook', 'facebookUrl'], ['instagram', 'instagramUrl'], ['x', 'xUrl'],
+  ['linkedin', 'linkedinUrl'], ['trustpilot', 'trustpilotUrl'],
+  ['facebook-ads', 'facebookAdsUrl'], ['google-ads', 'googleAdsUrl'], ['website', 'websiteUrl'],
+];
+
+export default {
+  description: 'Competitors — list, add, track, toggle insights/alerts, remove.',
+  commands: {
+    list: {
+      description: 'List tracked competitors.',
+      async handler(ctx) {
+        const list = await fetchCompetitors(ctx.profileName);
+        if (ctx.json) { out(list, ctx); return; }
+        const rows = list.map((c) => ({
+          name: c.name,
+          id: String(c._id),
+          tracking: c.isTracking ? 'on' : 'off',
+          insights: c.insightsEnabled ? 'on' : 'off',
+          alerts: c.alertsEnabled ? 'on' : 'off',
+          kind: c.isUserCompany ? 'company' : (c.watchOnly ? 'watch' : 'competitor'),
+        }));
+        table(rows, [
+          { key: 'name', label: 'NAME' }, { key: 'id', label: 'ID' },
+          { key: 'tracking', label: 'TRACK' }, { key: 'insights', label: 'INSIGHTS' },
+          { key: 'alerts', label: 'ALERTS' }, { key: 'kind', label: 'KIND' },
+        ], ctx);
+      },
+    },
+
+    show: {
+      description: 'Show one competitor (name substring or id).',
+      usage: 'comp show <name|id>',
+      async handler(ctx) {
+        const c = await resolveCompetitor(ctx.profileName, ctx.arg(0));
+        if (ctx.json) { out(c, ctx); return; }
+        kv({
+          name: c.name, id: String(c._id),
+          tracking: c.isTracking ? 'on' : 'off',
+          insights: c.insightsEnabled ? 'on' : 'off',
+          alerts: c.alertsEnabled ? 'on' : 'off',
+          kind: c.isUserCompany ? 'company' : (c.watchOnly ? 'watch-only' : 'competitor'),
+          website: (c.websiteUrls && c.websiteUrls[0]) || '—',
+        }, ctx);
+        if (c.socialSummary) {
+          info('');
+          const s = c.socialSummary;
+          const rows = Object.entries(s).map(([platform, v]) => ({
+            platform,
+            posts: v.totalPosts ?? 0,
+            followers: v.followers ?? v.totalFollowers ?? 0,
+            engagement: v.engagementRate ?? 0,
+          }));
+          table(rows, [
+            { key: 'platform', label: 'PLATFORM' }, { key: 'posts', label: 'POSTS' },
+            { key: 'followers', label: 'FOLLOWERS' }, { key: 'engagement', label: 'ENGAGE%' },
+          ], ctx);
+        }
+      },
+    },
+
+    add: {
+      description: 'Add a competitor. Provide at least one channel URL.',
+      usage: 'comp add <name> [--facebook url] [--instagram url] [--x url] [--linkedin url] [--trustpilot url] [--website url] [--company]',
+      flags: [
+        ...PLATFORM_FLAGS.map(([f]) => ({ name: f, description: `${f} URL` })),
+        { name: 'company', boolean: true, description: 'Mark as your own company (isUserCompany)' },
+      ],
+      async handler(ctx) {
+        const name = ctx.arg(0);
+        if (!name) throw new Error('Usage: oppira comp add <name> [--facebook url] ...');
+        const body = { name, isUserCompany: ctx.bool('company') };
+        for (const [flag, field] of PLATFORM_FLAGS) {
+          const v = ctx.flag(flag);
+          if (v) body[field] = v;
+        }
+        const res = await apiRequest(ctx.profileName, 'POST', '/competitors', { body });
+        if (ctx.json) { out(res, ctx); return; }
+        info(`✓ Created competitor "${name}"${res?.data?._id ? ` (${res.data._id})` : ''}. Scraping kicks off in the background.`);
+      },
+    },
+
+    track: {
+      description: 'Start tracking an existing competitor by id.',
+      usage: 'comp track <competitorId>',
+      async handler(ctx) {
+        const c = await resolveCompetitor(ctx.profileName, ctx.arg(0));
+        const res = await apiRequest(ctx.profileName, 'POST', '/competitors/track', { body: { competitorId: String(c._id) } });
+        if (ctx.json) { out(res, ctx); return; }
+        info(`✓ Tracking "${c.name}".`);
+      },
+    },
+
+    'toggle-tracking': {
+      description: 'Flip tracking on/off (subject to the 24h cooldown).',
+      usage: 'comp toggle-tracking <name|id>',
+      async handler(ctx) {
+        const c = await resolveCompetitor(ctx.profileName, ctx.arg(0));
+        const res = await apiRequest(ctx.profileName, 'PATCH', `/competitors/${c._id}/toggle-tracking`, { body: {} });
+        if (ctx.json) { out(res, ctx); return; }
+        info(`✓ Toggled tracking for "${c.name}". ${res?.message || ''}`);
+      },
+    },
+
+    insights: {
+      description: 'Toggle insight generation for a competitor.',
+      usage: 'comp insights <name|id>',
+      async handler(ctx) {
+        const c = await resolveCompetitor(ctx.profileName, ctx.arg(0));
+        const res = await apiRequest(ctx.profileName, 'PATCH', `/competitors/${c._id}/insights`, { body: {} });
+        if (ctx.json) { out(res, ctx); return; }
+        info(`✓ Toggled insights for "${c.name}". ${res?.message || ''}`);
+      },
+    },
+
+    alerts: {
+      description: 'Toggle alert generation for a competitor.',
+      usage: 'comp alerts <name|id>',
+      async handler(ctx) {
+        const c = await resolveCompetitor(ctx.profileName, ctx.arg(0));
+        const res = await apiRequest(ctx.profileName, 'PATCH', `/competitors/${c._id}/alerts`, { body: {} });
+        if (ctx.json) { out(res, ctx); return; }
+        info(`✓ Toggled alerts for "${c.name}". ${res?.message || ''}`);
+      },
+    },
+
+    rm: {
+      description: 'Delete a competitor.',
+      usage: 'comp rm <name|id> [--yes]',
+      flags: [{ name: 'yes', boolean: true, description: 'Skip confirmation' }],
+      async handler(ctx) {
+        const c = await resolveCompetitor(ctx.profileName, ctx.arg(0));
+        if (!ctx.bool('yes')) {
+          throw new Error(`Refusing to delete "${c.name}" without --yes.`);
+        }
+        const res = await apiRequest(ctx.profileName, 'DELETE', `/competitors/${c._id}`, {});
+        if (ctx.json) { out(res, ctx); return; }
+        info(`✓ Deleted "${c.name}".`);
+      },
+    },
+
+    // --- Analytics (local/ops mode — reuse the MCP tool implementations) ---
+    timeline: {
+      description: 'Per-month post metrics for a competitor (local mode).',
+      usage: 'comp timeline <name> [--months 6] [--email ...]',
+      flags: [
+        { name: 'months', description: 'Number of months (default engine max)' },
+        { name: 'email', description: 'User whose data to read (defaults to profile)' },
+      ],
+      async handler(ctx) {
+        const email = opsEmail(ctx);
+        const months = ctx.flag('months') ? Number(ctx.flag('months')) : undefined;
+        const result = await withDb(async () => {
+          const user = await findUserOrThrow(email);
+          const { id } = await resolveLocalId(user, ctx.arg(0));
+          const { getCompetitorTimeline } = await backendImport('mcp/mcpTools.js');
+          return getCompetitorTimeline({ competitorId: id, months }, { user });
+        });
+        out(result, ctx);
+      },
+    },
+
+    compare: {
+      description: 'Compare two competitors\' timelines (local mode).',
+      usage: 'comp compare <nameA> <nameB> [--months 6] [--email ...]',
+      flags: [
+        { name: 'months', description: 'Number of months' },
+        { name: 'email', description: 'User whose data to read (defaults to profile)' },
+      ],
+      async handler(ctx) {
+        const email = opsEmail(ctx);
+        const months = ctx.flag('months') ? Number(ctx.flag('months')) : undefined;
+        if (!ctx.arg(0) || !ctx.arg(1)) throw new Error('Usage: oppira comp compare <nameA> <nameB>');
+        const result = await withDb(async () => {
+          const user = await findUserOrThrow(email);
+          const a = await resolveLocalId(user, ctx.arg(0));
+          const b = await resolveLocalId(user, ctx.arg(1));
+          const { compareCompetitorsTimeline } = await backendImport('mcp/mcpTools.js');
+          return compareCompetitorsTimeline({ competitorIds: [a.id, b.id], months }, { user });
+        });
+        out(result, ctx);
+      },
+    },
+
+    'top-posts': {
+      description: 'Top posts across the period for a competitor (local mode).',
+      usage: 'comp top-posts <name> [--platform facebook] [--limit 10] [--email ...]',
+      flags: [
+        { name: 'platform', description: 'Filter by platform' },
+        { name: 'limit', description: 'Max posts' },
+        { name: 'email', description: 'User whose data to read (defaults to profile)' },
+      ],
+      async handler(ctx) {
+        const email = opsEmail(ctx);
+        const result = await withDb(async () => {
+          const user = await findUserOrThrow(email);
+          const { id } = await resolveLocalId(user, ctx.arg(0));
+          const { getTopPostsAcrossPeriod } = await backendImport('mcp/mcpTools.js');
+          return getTopPostsAcrossPeriod({
+            competitorId: id,
+            platform: ctx.flag('platform'),
+            limit: ctx.flag('limit') ? Number(ctx.flag('limit')) : undefined,
+          }, { user });
+        });
+        out(result, ctx);
+      },
+    },
+
+    tone: {
+      description: 'Tone / voice evolution for a competitor (local mode).',
+      usage: 'comp tone <name> [--limit 6] [--email ...]',
+      flags: [
+        { name: 'limit', description: 'Max tone profiles' },
+        { name: 'email', description: 'User whose data to read (defaults to profile)' },
+      ],
+      async handler(ctx) {
+        const email = opsEmail(ctx);
+        const result = await withDb(async () => {
+          const user = await findUserOrThrow(email);
+          const { id } = await resolveLocalId(user, ctx.arg(0));
+          const { getToneEvolution } = await backendImport('mcp/mcpTools.js');
+          return getToneEvolution({ competitorId: id, limit: ctx.flag('limit') ? Number(ctx.flag('limit')) : undefined }, { user });
+        });
+        out(result, ctx);
+      },
+    },
+  },
+};
+
+export { resolveCompetitor, fetchCompetitors };

package/src/commands/config.js

@@ -0,0 +1,64 @@
+// config: manage profiles (prod/staging, multiple accounts) and defaults.
+import { loadConfig, getProfile, setProfileValue, useProfile } from '../config.js';
+import { out, kv, table, info } from '../output.js';
+
+export default {
+  description: 'Config & profiles — API URL, default output, account switching.',
+  commands: {
+    show: {
+      description: 'Show the current profile and its settings.',
+      async handler(ctx) {
+        const cfg = loadConfig();
+        const profile = getProfile(ctx.profileName);
+        kv({ currentProfile: cfg.currentProfile, name: profile.name, apiUrl: profile.apiUrl, output: profile.output || 'table' }, ctx);
+      },
+    },
+
+    list: {
+      description: 'List all configured profiles.',
+      async handler(ctx) {
+        const cfg = loadConfig();
+        const rows = Object.entries(cfg.profiles).map(([name, p]) => ({
+          profile: name === cfg.currentProfile ? `* ${name}` : name,
+          apiUrl: p.apiUrl,
+          output: p.output || 'table',
+        }));
+        table(rows, [{ key: 'profile', label: 'PROFILE' }, { key: 'apiUrl', label: 'API URL' }, { key: 'output', label: 'OUTPUT' }], ctx);
+      },
+    },
+
+    'set-url': {
+      description: 'Set the API base URL for a profile.',
+      usage: 'config set-url <url> [--profile name]',
+      async handler(ctx) {
+        const url = ctx.arg(0);
+        if (!url) throw new Error('Usage: oppira config set-url <url>');
+        setProfileValue(ctx.profileName, 'apiUrl', url);
+        info(`✓ ${ctx.profileName}.apiUrl = ${url}`);
+      },
+    },
+
+    'set-output': {
+      description: 'Set default output format for a profile (table|json).',
+      usage: 'config set-output <table|json>',
+      async handler(ctx) {
+        const fmt = ctx.arg(0);
+        if (!['table', 'json'].includes(fmt)) throw new Error('Output must be "table" or "json".');
+        setProfileValue(ctx.profileName, 'output', fmt);
+        info(`✓ ${ctx.profileName}.output = ${fmt}`);
+      },
+    },
+
+    use: {
+      description: 'Switch the active profile.',
+      usage: 'config use <name>',
+      async handler(ctx) {
+        const name = ctx.arg(0);
+        if (!name) throw new Error('Usage: oppira config use <name>');
+        useProfile(name);
+        if (ctx.json) { out({ success: true, currentProfile: name }, ctx); return; }
+        info(`✓ Switched to profile "${name}".`);
+      },
+    },
+  },
+};

package/src/commands/discover.js

@@ -0,0 +1,87 @@
+// discover: find social profiles for a company (async job) + manage the
+// weekly competitor suggestions.
+import { apiRequest } from '../http.js';
+import { out, table, info } from '../output.js';
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+export default {
+  description: 'Discovery — find profiles for a company and manage suggestions.',
+  commands: {
+    profiles: {
+      description: 'Discover social profiles for a company (async job).',
+      usage: 'discover profiles --domain acme.com [--name Acme] [--region US] [--no-wait]',
+      flags: [
+        { name: 'domain', description: 'Company domain (e.g. acme.com)' },
+        { name: 'name', description: 'Company name' },
+        { name: 'region', description: 'Region hint (e.g. US, EU)' },
+        { name: 'no-wait', boolean: true, description: 'Enqueue and return the job id without polling' },
+      ],
+      async handler(ctx) {
+        const domain = ctx.flag('domain');
+        const name = ctx.flag('name');
+        if (!domain && !name) throw new Error('Provide at least --domain or --name.');
+        const res = await apiRequest(ctx.profileName, 'POST', '/discovery/profiles', {
+          body: { domain, name, region: ctx.flag('region') },
+        });
+        const jobId = res?.jobId || res?.data?.jobId || res?.id;
+        if (!jobId) { out(res, ctx); return; }
+        if (ctx.bool('no-wait')) {
+          if (ctx.json) { out({ jobId }, ctx); return; }
+          info(`✓ Discovery job queued: ${jobId} (poll: oppira discover job ${jobId})`);
+          return;
+        }
+        info(`Discovery job ${jobId} queued — polling…`);
+        for (let i = 0; i < 20; i++) {
+          await sleep(3000);
+          const job = await apiRequest(ctx.profileName, 'GET', `/discovery/jobs/${jobId}`);
+          const status = job?.status || job?.data?.status;
+          if (status && !['pending', 'processing', 'queued', 'running'].includes(status)) {
+            out(job, ctx);
+            return;
+          }
+          if (!ctx.json) info(`  …${status || 'working'}`);
+        }
+        info('Still running — check later with: oppira discover job ' + jobId);
+      },
+    },
+
+    job: {
+      description: 'Check a discovery job by id.',
+      usage: 'discover job <jobId>',
+      async handler(ctx) {
+        const jobId = ctx.arg(0);
+        if (!jobId) throw new Error('Usage: oppira discover job <jobId>');
+        const job = await apiRequest(ctx.profileName, 'GET', `/discovery/jobs/${jobId}`);
+        out(job, ctx);
+      },
+    },
+
+    suggestions: {
+      description: 'List competitor suggestions.',
+      async handler(ctx) {
+        const res = await apiRequest(ctx.profileName, 'GET', '/competitor-suggestions');
+        const list = res?.data || res?.suggestions || res || [];
+        if (ctx.json) { out(list, ctx); return; }
+        const rows = (Array.isArray(list) ? list : []).map((s) => ({
+          id: String(s._id || s.id || '—'),
+          name: s.name || s.companyName || '—',
+          reason: s.reason || s.rationale || '—',
+        }));
+        table(rows, [{ key: 'id', label: 'ID' }, { key: 'name', label: 'NAME' }, { key: 'reason', label: 'REASON', max: 60 }], ctx);
+      },
+    },
+
+    dismiss: {
+      description: 'Dismiss a competitor suggestion by id.',
+      usage: 'discover dismiss <id>',
+      async handler(ctx) {
+        const id = ctx.arg(0);
+        if (!id) throw new Error('Usage: oppira discover dismiss <id>');
+        const res = await apiRequest(ctx.profileName, 'POST', `/competitor-suggestions/${id}/dismiss`, { body: {} });
+        if (ctx.json) { out(res, ctx); return; }
+        info(`✓ Dismissed suggestion ${id}.`);
+      },
+    },
+  },
+};

package/src/commands/insights.js

@@ -0,0 +1,76 @@
+// insights: read (REST) + force-generate (local engine, cron-only otherwise).
+import { apiRequest } from '../http.js';
+import { getCredentials } from '../config.js';
+import { withDb, findUserOrThrow, backendImport } from '../local.js';
+import { out, table, info, kv } from '../output.js';
+
+function opsEmail(ctx) {
+  const email = ctx.flag('email') || getCredentials(ctx.profileName).email;
+  if (!email) throw new Error('Provide --email (or log in) to select the target user.');
+  return email;
+}
+
+export default {
+  description: 'Insights — list cards, weekly summary, and force-generate (ops).',
+  commands: {
+    list: {
+      description: 'List AI insight cards.',
+      async handler(ctx) {
+        const res = await apiRequest(ctx.profileName, 'GET', '/insights');
+        const cards = res?.data || res?.insights || res || [];
+        if (ctx.json) { out(cards, ctx); return; }
+        const rows = (Array.isArray(cards) ? cards : []).map((c) => ({
+          type: c.type || c.category || '—',
+          title: c.title || c.headline || '—',
+          competitor: c.competitorName || c.competitor || '—',
+          read: c.read || c.isRead ? 'yes' : 'no',
+        }));
+        table(rows, [
+          { key: 'type', label: 'TYPE' }, { key: 'title', label: 'TITLE', max: 60 },
+          { key: 'competitor', label: 'COMPETITOR' }, { key: 'read', label: 'READ' },
+        ], ctx);
+      },
+    },
+
+    summary: {
+      description: 'Show the weekly actionable summary.',
+      async handler(ctx) {
+        const res = await apiRequest(ctx.profileName, 'GET', '/insights/actionable-summary');
+        if (ctx.json) { out(res, ctx); return; }
+        const s = res?.data || res?.summary || res;
+        if (!s) { info('(no summary yet)'); return; }
+        kv({ generatedAt: s.createdAt || s.generatedAt || '—', title: s.title || '—' }, ctx);
+        if (s.body || s.content) { info(''); info(s.body || s.content); }
+        else out(s, ctx);
+      },
+    },
+
+    generate: {
+      description: 'Force-generate insights now (remote by default; --local runs the engine directly).',
+      usage: 'insights generate [--local] [--email you@co.com]',
+      flags: [
+        { name: 'local', boolean: true, description: 'Run the engine directly (ops; needs repo + .env)' },
+        { name: 'email', description: 'Target user in --local mode (defaults to logged-in profile)' },
+      ],
+      async handler(ctx) {
+        if (!ctx.useLocal) {
+          // Remote: the authenticated user generates their own insights.
+          const res = await apiRequest(ctx.profileName, 'POST', '/insights/generate', { body: {} });
+          if (ctx.json) { out(res, ctx); return; }
+          info('✓ Insights generation triggered.');
+          if (res?.result) out(res.result, ctx);
+          return;
+        }
+        const email = opsEmail(ctx);
+        const result = await withDb(async () => {
+          const user = await findUserOrThrow(email);
+          const { generateInsightsForUser } = await backendImport('utils/weeklyInsightsGenerator.js');
+          return generateInsightsForUser(user);
+        });
+        if (ctx.json) { out({ success: true, email, result }, ctx); return; }
+        info(`✓ Insights generation run for ${email} (local).`);
+        if (result) out(result, ctx);
+      },
+    },
+  },
+};

package/src/commands/playbook.js

@@ -0,0 +1,79 @@
+// playbook: read the strategy doc, bootstrap it, and refresh sections/clusters.
+// All REST (JWT), gated by requirePlaybookAccess + quota on the backend.
+import { apiRequest } from '../http.js';
+import { getCredentials } from '../config.js';
+import { out, kv, info } from '../output.js';
+
+function playbookEmail(ctx) {
+  const email = ctx.flag('email') || getCredentials(ctx.profileName).email;
+  if (!email) throw new Error('Provide --email (or log in) to select the playbook owner.');
+  return encodeURIComponent(email);
+}
+
+export default {
+  description: 'Marketing playbook — show, bootstrap, refresh sections/clusters.',
+  commands: {
+    show: {
+      description: 'Show the playbook (use --json for the full document).',
+      usage: 'playbook show [--email you@co.com]',
+      flags: [{ name: 'email', description: 'Playbook owner (defaults to logged-in profile)' }],
+      async handler(ctx) {
+        const email = playbookEmail(ctx);
+        const res = await apiRequest(ctx.profileName, 'GET', `/playbook/${email}`);
+        if (ctx.json) { out(res, ctx); return; }
+        const pb = res?.data || res?.playbook || res;
+        if (!pb) { info('(no playbook yet — run: oppira playbook bootstrap)'); return; }
+        kv({
+          updatedAt: pb.updatedAt || '—',
+          sections: Array.isArray(pb.sections) ? pb.sections.length : (pb.sections ? Object.keys(pb.sections).length : '—'),
+          status: pb.status || '—',
+        }, ctx);
+        if (Array.isArray(pb.sections)) {
+          info('');
+          for (const s of pb.sections) info(`- ${s.id || s.key || ''}: ${s.title || ''}`);
+        }
+        info('\n(use --json for the full document)');
+      },
+    },
+
+    bootstrap: {
+      description: 'Bootstrap / (re)build the playbook.',
+      usage: 'playbook bootstrap [--email you@co.com]',
+      flags: [{ name: 'email', description: 'Playbook owner (defaults to logged-in profile)' }],
+      async handler(ctx) {
+        const email = playbookEmail(ctx);
+        const res = await apiRequest(ctx.profileName, 'POST', `/playbook/${email}/bootstrap`, { body: {} });
+        if (ctx.json) { out(res, ctx); return; }
+        info(`✓ Playbook bootstrap triggered. ${res?.message || ''}`);
+      },
+    },
+
+    'refresh-section': {
+      description: 'Refresh a single playbook section.',
+      usage: 'playbook refresh-section <sectionId> [--email ...]',
+      flags: [{ name: 'email', description: 'Playbook owner' }],
+      async handler(ctx) {
+        const email = playbookEmail(ctx);
+        const sectionId = ctx.arg(0);
+        if (!sectionId) throw new Error('Usage: oppira playbook refresh-section <sectionId>');
+        const res = await apiRequest(ctx.profileName, 'POST', `/playbook/${email}/section/${encodeURIComponent(sectionId)}/refresh`, { body: {} });
+        if (ctx.json) { out(res, ctx); return; }
+        info(`✓ Section "${sectionId}" refresh triggered. ${res?.message || ''}`);
+      },
+    },
+
+    'refresh-cluster': {
+      description: 'Refresh a playbook cluster (c1/c2/c4).',
+      usage: 'playbook refresh-cluster <clusterId> [--email ...]',
+      flags: [{ name: 'email', description: 'Playbook owner' }],
+      async handler(ctx) {
+        const email = playbookEmail(ctx);
+        const clusterId = ctx.arg(0);
+        if (!clusterId) throw new Error('Usage: oppira playbook refresh-cluster <clusterId>');
+        const res = await apiRequest(ctx.profileName, 'POST', `/playbook/${email}/cluster/${encodeURIComponent(clusterId)}/refresh`, { body: {} });
+        if (ctx.json) { out(res, ctx); return; }
+        info(`✓ Cluster "${clusterId}" refresh triggered. ${res?.message || ''}`);
+      },
+    },
+  },
+};