@blockrun/franklin 3.1.2 → 3.2.1

package/dist/banner.js

@@ -1,5 +1,39 @@
 import chalk from 'chalk';
-// "FRANKLIN" — the AI agent with a wallet
+// ─── Ben Franklin portrait ─────────────────────────────────────────────────
+//
+// Generated once, at build time, from the Joseph Duplessis 1785 oil painting
+// of Benjamin Franklin (same source as the portrait on the US $100 bill).
+// Public domain image from Wikimedia Commons:
+//   https://commons.wikimedia.org/wiki/File:BenFranklinDuplessis.jpg
+//
+// Rendered via chafa with:
+//   chafa --size=20x10 --symbols=block --colors=256 ben-franklin.jpg
+//
+// The raw ANSI escape codes are hex-encoded below so the TS source stays
+// readable and diff-friendly. Each string is one row of the portrait.
+// Visible dimensions: ~17 characters wide × 10 rows tall.
+//
+// Rendered best in a 256-color or truecolor terminal. Degrades gracefully
+// (shows as block-character garbage) on ancient terminals — but those
+// are long gone and we don't support them.
+const BEN_PORTRAIT_ROWS = [
+    '\x1b[0m\x1b[38;5;232;48;5;16m▏     \x1b[48;5;232m  \x1b[48;5;16m▂\x1b[48;5;232m    \x1b[38;5;233m▃▃\x1b[48;5;233m  \x1b[0m',
+    '\x1b[38;5;232;48;5;16m▏    \x1b[38;5;234m▂\x1b[38;5;95;48;5;232m▄\x1b[38;5;137;48;5;233m▅\x1b[38;5;173m▅\x1b[38;5;137;48;5;234m▃\x1b[38;5;235;48;5;233m▁    \x1b[38;5;234m▄ \x1b[0m',
+    '\x1b[38;5;232;48;5;16m▏▕  \x1b[38;5;234;48;5;232m▁\x1b[38;5;235;48;5;237m▎\x1b[38;5;58;48;5;179m▌\x1b[38;5;131m▄\x1b[38;5;94m▖\x1b[38;5;58;48;5;137m▗\x1b[48;5;235m▍\x1b[38;5;235;48;5;234m▆▆▄▅  \x1b[0m',
+    '\x1b[38;5;233;48;5;232m▏\x1b[38;5;232;48;5;16m▏\x1b[38;5;16;48;5;232m▏\x1b[38;5;233m▗\x1b[38;5;236;48;5;240m▎\x1b[38;5;235;48;5;238m▄\x1b[38;5;95;48;5;173m▎\x1b[38;5;173;48;5;179m▖\x1b[38;5;137m▁\x1b[48;5;94m▍\x1b[38;5;94;48;5;233m▋\x1b[38;5;233;48;5;235m▖\x1b[38;5;236m▄  \x1b[38;5;235;48;5;234m▌ \x1b[0m',
+    '\x1b[38;5;233;48;5;232m▏  \x1b[38;5;232;48;5;234m▌\x1b[38;5;240;48;5;236m▁\x1b[38;5;95;48;5;235m▁\x1b[38;5;186;48;5;137m▗ \x1b[38;5;95;48;5;173m▃\x1b[38;5;137;48;5;94m▘\x1b[38;5;58;48;5;234m▍\x1b[38;5;234;48;5;236m▘ \x1b[38;5;236;48;5;235m▏  \x1b[38;5;232;48;5;234m▄\x1b[0m',
+    '\x1b[38;5;233;48;5;232m▏\x1b[38;5;235m▁\x1b[38;5;95;48;5;234m▄\x1b[38;5;137;48;5;236m▆\x1b[48;5;95m \x1b[38;5;101m▁\x1b[38;5;137m▔\x1b[48;5;186m▄\x1b[48;5;95m▍\x1b[48;5;236m▃\x1b[38;5;143;48;5;235m▃\x1b[38;5;236m▏\x1b[38;5;235;48;5;236m▃\x1b[48;5;235m \x1b[38;5;234m▁\x1b[38;5;235;48;5;232m▘\x1b[38;5;232;48;5;16m▔\x1b[0m',
+    '\x1b[38;5;238;48;5;233m▗\x1b[38;5;8;48;5;137m▘\x1b[38;5;138m▘ \x1b[38;5;137;48;5;95m▊\x1b[38;5;95;48;5;101m▎\x1b[38;5;137;48;5;95m▎\x1b[48;5;101m▌\x1b[48;5;95m \x1b[38;5;95;48;5;101m▏\x1b[38;5;143m▔\x1b[38;5;101;48;5;236m▅\x1b[38;5;240;48;5;234m▖\x1b[38;5;235m▞\x1b[38;5;234;48;5;232m▘\x1b[38;5;232;48;5;16m▔ \x1b[0m',
+    '\x1b[38;5;52;48;5;95m▋\x1b[48;5;137m   \x1b[38;5;95;48;5;101m▕\x1b[38;5;240;48;5;137m▌\x1b[38;5;101m▂ \x1b[48;5;95m▏\x1b[38;5;239m▖▂\x1b[38;5;237m▄\x1b[38;5;101;48;5;234m▘\x1b[38;5;234;48;5;233m▝\x1b[48;5;232m▖\x1b[48;5;16m  \x1b[0m',
+    '\x1b[38;5;235;48;5;95m▌\x1b[38;5;95;48;5;137m▄\x1b[38;5;101m▁ \x1b[48;5;95m▌\x1b[38;5;238m▋\x1b[38;5;240;48;5;101m▃ \x1b[38;5;95;48;5;240m▎\x1b[38;5;236;48;5;239m▝\x1b[38;5;95;48;5;235m▆\x1b[38;5;240m▆\x1b[38;5;237;48;5;233m▆\x1b[48;5;234m▃\x1b[38;5;235;48;5;233m▎\x1b[38;5;233;48;5;232m▖\x1b[48;5;16m \x1b[0m',
+    '\x1b[38;5;234;48;5;95m▌  \x1b[38;5;95;48;5;101m▃\x1b[38;5;239;48;5;95m▗\x1b[38;5;238;48;5;234m▋\x1b[38;5;236;48;5;101m▎\x1b[38;5;101;48;5;95m▋\x1b[38;5;239m▂▎  \x1b[48;5;240m▃\x1b[38;5;8;48;5;236m▍\x1b[38;5;235;48;5;233m▋\x1b[38;5;232m▅\x1b[38;5;233;48;5;232m▖\x1b[0m',
+];
+// ─── FRANKLIN text banner (gold → emerald gradient) ────────────────────────
+//
+// Kept from v3.1.0. The text is laid out as 6 block-letter rows. Each row
+// is tinted with a color interpolated between GOLD_START and EMERALD_END,
+// giving the smooth vertical gradient that's been Franklin's banner since
+// v3.1.0.
 const FRANKLIN_ART = [
     ' ███████╗██████╗  █████╗ ███╗   ██╗██╗  ██╗██╗     ██╗███╗   ██╗',
     ' ██╔════╝██╔══██╗██╔══██╗████╗  ██║██║ ██╔╝██║     ██║████╗  ██║',
@@ -8,10 +42,6 @@ const FRANKLIN_ART = [
     ' ██║     ██║  ██║██║  ██║██║ ╚████║██║  ██╗███████╗██║██║ ╚████║',
     ' ╚═╝     ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═══╝╚═╝  ╚═╝╚══════╝╚═╝╚═╝  ╚═══╝',
 ];
-// Franklin brand gradient: gold → emerald
-// Gold (#FFD700) is the $100 bill / Benjamins color — marketing product energy
-// Emerald (#10B981) is the trading / money-moving color
-// The gradient between them tells the Franklin story in one glance
 const GOLD_START = '#FFD700';
 const EMERALD_END = '#10B981';
 function hexToRgb(hex) {
@@ -31,11 +61,97 @@ function interpolateHex(start, end, t) {
     const [r2, g2, b2] = hexToRgb(end);
     return rgbToHex(r1 + (r2 - r1) * t, g1 + (g2 - g1) * t, b1 + (b2 - b1) * t);
 }
+// ─── Banner layout ─────────────────────────────────────────────────────────
+// Minimum terminal width to show the side-by-side portrait + text layout.
+// The portrait is ~17 chars, the FRANKLIN text is ~65 chars, plus a 4-char
+// gap = 86 chars. We add a small margin so ~90 cols is the threshold.
+const MIN_WIDTH_FOR_PORTRAIT = 90;
+/**
+ * Pad a line to an exact visual width, ignoring ANSI escape codes when
+ * measuring. Used to align the portrait's right edge before the text block.
+ */
+function padVisible(s, targetWidth) {
+    // Strip ANSI color codes to measure visible length
+    // eslint-disable-next-line no-control-regex
+    const visible = s.replace(/\x1b\[[0-9;]*m/g, '');
+    // Unicode block characters are width 1 (they're half-blocks, not double-width)
+    const current = [...visible].length;
+    if (current >= targetWidth)
+        return s;
+    // Append a reset + padding so background colors don't bleed into the gap
+    return s + '\x1b[0m' + ' '.repeat(targetWidth - current);
+}
 export function printBanner(version) {
-    // Smooth 6-row gradient: each line gets its own interpolated color
-    const steps = FRANKLIN_ART.length;
-    for (let i = 0; i < steps; i++) {
-        const t = i / (steps - 1);
+    const termWidth = process.stdout.columns ?? 80;
+    const useSideBySide = termWidth >= MIN_WIDTH_FOR_PORTRAIT;
+    if (useSideBySide) {
+        printSideBySide(version);
+    }
+    else {
+        printTextOnly(version);
+    }
+}
+/**
+ * Full layout: Ben Franklin portrait on the left, FRANKLIN text block on the
+ * right. Portrait is 10 rows, text is 6 rows — portrait extends 4 rows below
+ * the text, so the 2-row tagline sits under the text and the last 2 rows
+ * below the portrait are just the bottom of the portrait.
+ *
+ *   [portrait row 1]                [empty]
+ *   [portrait row 2]                [empty]
+ *   [portrait row 3]     ███████╗██████╗  █████╗ ...
+ *   [portrait row 4]     ██╔════╝██╔══██╗██╔══██╗...
+ *   [portrait row 5]     █████╗  ██████╔╝███████║...
+ *   [portrait row 6]     ██╔══╝  ██╔══██╗██╔══██║...
+ *   [portrait row 7]     ██║     ██║  ██║██║  ██║...
+ *   [portrait row 8]     ╚═╝     ╚═╝  ╚═╝╚═╝  ╚═╝...
+ *   [portrait row 9]     Franklin · The AI agent with a wallet · vX
+ *   [portrait row 10]    (empty)
+ *
+ * The text is vertically centered within the portrait — its top edge sits
+ * at portrait row 3 so there's a 2-row header padding above.
+ */
+function printSideBySide(version) {
+    const TEXT_TOP_OFFSET = 2; // rows of portrait above the text
+    const PORTRAIT_WIDTH = 18; // columns (char width) of the portrait + 1 pad
+    const GAP = '  '; // gap between portrait and text
+    const portraitRows = BEN_PORTRAIT_ROWS;
+    const textRows = FRANKLIN_ART.length;
+    const totalRows = Math.max(portraitRows.length, TEXT_TOP_OFFSET + textRows + 2);
+    for (let i = 0; i < totalRows; i++) {
+        const portraitLine = i < portraitRows.length
+            ? padVisible(portraitRows[i], PORTRAIT_WIDTH)
+            : ' '.repeat(PORTRAIT_WIDTH);
+        // Text column content
+        let textCol = '';
+        const textIdx = i - TEXT_TOP_OFFSET;
+        if (textIdx >= 0 && textIdx < textRows) {
+            // FRANKLIN block letters with gradient colour
+            const t = textRows === 1 ? 0 : textIdx / (textRows - 1);
+            const color = interpolateHex(GOLD_START, EMERALD_END, t);
+            textCol = chalk.hex(color)(FRANKLIN_ART[textIdx]);
+        }
+        else if (textIdx === textRows) {
+            // Tagline row sits right under the FRANKLIN block
+            textCol =
+                chalk.bold.hex(GOLD_START)('  Franklin') +
+                    chalk.dim('  ·  The AI agent with a wallet  ·  v' + version);
+        }
+        // Write with a reset at the very start to prevent stray bg from the
+        // previous line bleeding into the current row's portrait column.
+        process.stdout.write('\x1b[0m' + portraitLine + GAP + textCol + '\x1b[0m\n');
+    }
+    // Trailing blank line for breathing room
+    process.stdout.write('\n');
+}
+/**
+ * Compact layout for narrow terminals: just the FRANKLIN text block with
+ * its gradient, no portrait. Matches the v3.1.0 banner exactly.
+ */
+function printTextOnly(version) {
+    const textRows = FRANKLIN_ART.length;
+    for (let i = 0; i < textRows; i++) {
+        const t = textRows === 1 ? 0 : i / (textRows - 1);
         const color = interpolateHex(GOLD_START, EMERALD_END, t);
         console.log(chalk.hex(color)(FRANKLIN_ART[i]));
     }

package/dist/commands/social.d.ts

@@ -0,0 +1,24 @@
+/**
+ * franklin social <action>
+ *
+ * Native X bot subsystem. No MCP, no plugin SDK, no external CLI deps.
+ * Ships as part of the core npm package; only runtime dep is playwright-core,
+ * which is lazy-imported so startup stays fast.
+ *
+ * Actions:
+ *   setup     — install chromium via playwright, write default config
+ *   login x   — open browser to x.com and wait for user to log in; save state
+ *   run       — search X, generate drafts, post (requires --live) or dry-run
+ *   stats     — show posted/skipped/drafted counts and total cost
+ *   config    — open ~/.blockrun/social-config.json for manual editing
+ */
+export interface SocialCommandOptions {
+    dryRun?: boolean;
+    live?: boolean;
+    model?: string;
+    debug?: boolean;
+}
+/**
+ * Entry point wired from src/index.ts as `franklin social [action] [arg]`.
+ */
+export declare function socialCommand(action: string | undefined, arg: string | undefined, options: SocialCommandOptions): Promise<void>;

package/dist/commands/social.js

@@ -0,0 +1,258 @@
+/**
+ * franklin social <action>
+ *
+ * Native X bot subsystem. No MCP, no plugin SDK, no external CLI deps.
+ * Ships as part of the core npm package; only runtime dep is playwright-core,
+ * which is lazy-imported so startup stays fast.
+ *
+ * Actions:
+ *   setup     — install chromium via playwright, write default config
+ *   login x   — open browser to x.com and wait for user to log in; save state
+ *   run       — search X, generate drafts, post (requires --live) or dry-run
+ *   stats     — show posted/skipped/drafted counts and total cost
+ *   config    — open ~/.blockrun/social-config.json for manual editing
+ */
+import chalk from 'chalk';
+import fs from 'node:fs';
+import { spawn } from 'node:child_process';
+import { loadConfig as loadSocialConfig, saveConfig as saveSocialConfig, isConfigReady, CONFIG_PATH, } from '../social/config.js';
+import { SocialBrowser, SOCIAL_PROFILE_DIR } from '../social/browser.js';
+import { runX } from '../social/x.js';
+import { getStats } from '../social/db.js';
+import { loadChain, API_URLS } from '../config.js';
+import { loadConfig as loadAppConfig } from './config.js';
+/**
+ * Entry point wired from src/index.ts as `franklin social [action] [arg]`.
+ */
+export async function socialCommand(action, arg, options) {
+    switch (action) {
+        case undefined:
+        case 'help':
+            printHelp();
+            return;
+        case 'setup':
+            await setupCommand();
+            return;
+        case 'login':
+            await loginCommand(arg);
+            return;
+        case 'run':
+            await runCommand(options);
+            return;
+        case 'stats':
+            statsCommand();
+            return;
+        case 'config':
+            configCommand(arg);
+            return;
+        default:
+            console.log(chalk.red(`Unknown social action: ${action}`));
+            printHelp();
+            process.exitCode = 1;
+    }
+}
+// ─── help ──────────────────────────────────────────────────────────────────
+function printHelp() {
+    console.log('');
+    console.log(chalk.bold('  franklin social') + chalk.dim(' — native X bot (no MCP, no plugin deps)'));
+    console.log('');
+    console.log('  Actions:');
+    console.log(`    ${chalk.cyan('setup')}       Install chromium, create default config`);
+    console.log(`    ${chalk.cyan('login x')}     Open browser to x.com, save login state`);
+    console.log(`    ${chalk.cyan('run')}         Search X, generate + (optionally) post replies`);
+    console.log(`                ${chalk.dim('--dry-run  (default) generate drafts, do NOT post')}`);
+    console.log(`                ${chalk.dim('--live     actually post to X')}`);
+    console.log(`                ${chalk.dim('-m <model> override the AI model')}`);
+    console.log(`    ${chalk.cyan('stats')}       Show posted / drafted / skipped totals`);
+    console.log(`    ${chalk.cyan('config')}      Print the path to the config file (or pass edit)`);
+    console.log('');
+    console.log(`  Config:  ${chalk.dim(CONFIG_PATH)}`);
+    console.log(`  Profile: ${chalk.dim(SOCIAL_PROFILE_DIR)}`);
+    console.log('');
+    console.log('  Typical first-run flow:');
+    console.log(`    ${chalk.cyan('$')} franklin social setup`);
+    console.log(`    ${chalk.cyan('$')} franklin social config edit     ${chalk.dim('# set handle, products, queries')}`);
+    console.log(`    ${chalk.cyan('$')} franklin social login x         ${chalk.dim('# log in once; cookies persist')}`);
+    console.log(`    ${chalk.cyan('$')} franklin social run             ${chalk.dim('# dry-run, preview drafts')}`);
+    console.log(`    ${chalk.cyan('$')} franklin social run --live      ${chalk.dim('# actually post')}`);
+    console.log('');
+}
+// ─── setup ────────────────────────────────────────────────────────────────
+async function setupCommand() {
+    console.log(chalk.bold('\n  Franklin social — setup\n'));
+    // 1. Install chromium via playwright CLI (ships with playwright-core)
+    console.log(chalk.dim('  Installing chromium for the social browser…'));
+    console.log(chalk.dim('  (~150MB, one-time download to ~/.cache/ms-playwright)\n'));
+    await runChild('npx', ['playwright', 'install', 'chromium']);
+    // 2. Ensure profile dir exists
+    if (!fs.existsSync(SOCIAL_PROFILE_DIR)) {
+        fs.mkdirSync(SOCIAL_PROFILE_DIR, { recursive: true });
+        console.log(chalk.green(`  ✓ Created Chrome profile at ${SOCIAL_PROFILE_DIR}`));
+    }
+    // 3. Write default config if missing
+    const config = loadSocialConfig();
+    saveSocialConfig(config); // touches file so the user can edit
+    console.log(chalk.green(`  ✓ Config ready at ${CONFIG_PATH}`));
+    console.log('');
+    console.log(chalk.bold('  Next steps:'));
+    console.log(`    1. ${chalk.cyan('franklin social config edit')}    edit handle, products, search queries`);
+    console.log(`    2. ${chalk.cyan('franklin social login x')}        log in to x.com (once — cookies persist)`);
+    console.log(`    3. ${chalk.cyan('franklin social run')}            dry-run to preview drafts`);
+    console.log('');
+}
+// ─── login ─────────────────────────────────────────────────────────────────
+async function loginCommand(platform) {
+    if (platform !== 'x') {
+        console.log(chalk.red(`Only "x" is supported. Usage: franklin social login x`));
+        process.exitCode = 1;
+        return;
+    }
+    console.log(chalk.bold('\n  Opening x.com for login…\n'));
+    console.log(chalk.dim('  A Chrome window will open. Log in to your X account,'));
+    console.log(chalk.dim('  then close the window when done. Cookies will persist'));
+    console.log(chalk.dim(`  at ${SOCIAL_PROFILE_DIR}\n`));
+    const browser = new SocialBrowser({ headless: false });
+    try {
+        await browser.launch();
+        await browser.open('https://x.com/login');
+        console.log(chalk.yellow('  Waiting for you to log in and close the browser…'));
+        await browser.waitForClose();
+        console.log(chalk.green('\n  ✓ Browser closed — session state saved.'));
+        console.log(chalk.dim(`  Next: franklin social config edit  (then: franklin social run)\n`));
+    }
+    catch (err) {
+        console.error(chalk.red(`  ✗ ${err.message}`));
+        process.exitCode = 1;
+    }
+    finally {
+        await browser.close().catch(() => { });
+    }
+}
+// ─── run ───────────────────────────────────────────────────────────────────
+async function runCommand(options) {
+    let config;
+    try {
+        config = loadSocialConfig();
+    }
+    catch (err) {
+        console.error(chalk.red(`  ✗ Config error: ${err.message}`));
+        console.error(chalk.dim(`  Run: franklin social setup`));
+        process.exitCode = 1;
+        return;
+    }
+    const ready = isConfigReady(config);
+    if (!ready.ready) {
+        console.error(chalk.red(`  ✗ Config not ready: ${ready.reason}`));
+        console.error(chalk.dim(`  Edit: ${CONFIG_PATH}`));
+        process.exitCode = 1;
+        return;
+    }
+    const dryRun = !options.live; // --live overrides default dry-run
+    const mode = dryRun ? 'DRY-RUN' : chalk.bold.red('LIVE');
+    console.log('');
+    console.log(chalk.bold(`  franklin social run ${chalk.dim(`(${mode})`)}\n`));
+    console.log(`  Handle:   ${chalk.cyan(config.handle)}`);
+    console.log(`  Products: ${config.products.map((p) => p.name).join(', ')}`);
+    console.log(`  Queries:  ${config.x.search_queries.length}`);
+    console.log(`  Daily:    ${config.x.daily_target} posts`);
+    console.log('');
+    const chain = loadChain();
+    const apiUrl = API_URLS[chain];
+    const appConfig = loadAppConfig();
+    const model = options.model || appConfig['default-model'] || 'nvidia/nemotron-ultra-253b';
+    console.log(chalk.dim(`  Model: ${model}`));
+    console.log('');
+    let result;
+    try {
+        result = await runX({
+            config,
+            model,
+            apiUrl,
+            chain,
+            dryRun,
+            debug: options.debug,
+            onProgress: (msg) => process.stdout.write(msg + '\n'),
+        });
+    }
+    catch (err) {
+        console.error(chalk.red(`\n  ✗ Run failed: ${err.message}`));
+        process.exitCode = 1;
+        return;
+    }
+    console.log('');
+    console.log(chalk.bold('  Run summary:'));
+    console.log(`    Considered:   ${result.considered}`);
+    console.log(`    Dedup skips:  ${chalk.dim(result.dedupSkipped)}`);
+    console.log(`    AI SKIPs:     ${chalk.dim(result.llmSkipped)}`);
+    console.log(`    Drafted:      ${chalk.green(result.drafted)}`);
+    if (!dryRun) {
+        console.log(`    Posted:       ${chalk.green.bold(result.posted)}`);
+        console.log(`    Failed:       ${result.failed > 0 ? chalk.red(result.failed) : 0}`);
+    }
+    console.log(`    LLM cost:     ${chalk.yellow('$' + result.totalCost.toFixed(4))}`);
+    console.log('');
+}
+// ─── stats ─────────────────────────────────────────────────────────────────
+function statsCommand() {
+    const s = getStats('x');
+    console.log('');
+    console.log(chalk.bold('  franklin social stats — X'));
+    console.log('');
+    console.log(`    Total events:   ${s.total}`);
+    console.log(`    ✓ Posted:       ${chalk.green(s.posted)}  ${s.today > 0 ? chalk.dim(`(${s.today} today)`) : ''}`);
+    console.log(`    ≡ Drafted:      ${s.drafted}`);
+    console.log(`    · Skipped (AI): ${chalk.dim(s.skipped)}`);
+    console.log(`    ✗ Failed:       ${s.failed > 0 ? chalk.red(s.failed) : 0}`);
+    console.log(`    Total LLM cost: ${chalk.yellow('$' + s.totalCost.toFixed(4))}`);
+    if (Object.keys(s.byProduct).length > 0) {
+        console.log('');
+        console.log('    By product:');
+        for (const [name, count] of Object.entries(s.byProduct)) {
+            console.log(`      ${name.padEnd(20)} ${count}`);
+        }
+    }
+    console.log('');
+}
+// ─── config ────────────────────────────────────────────────────────────────
+function configCommand(subAction) {
+    if (!subAction || subAction === 'path') {
+        console.log(CONFIG_PATH);
+        return;
+    }
+    if (subAction === 'show' || subAction === 'print') {
+        if (!fs.existsSync(CONFIG_PATH)) {
+            console.log(chalk.yellow(`  Config not found at ${CONFIG_PATH}`));
+            console.log(chalk.dim(`  Run: franklin social setup`));
+            return;
+        }
+        console.log(fs.readFileSync(CONFIG_PATH, 'utf8'));
+        return;
+    }
+    if (subAction === 'edit' || subAction === 'open') {
+        if (!fs.existsSync(CONFIG_PATH)) {
+            loadSocialConfig(); // writes the default file
+        }
+        const editor = process.env.EDITOR || (process.platform === 'darwin' ? 'open' : 'vi');
+        const args = editor === 'open' ? ['-t', CONFIG_PATH] : [CONFIG_PATH];
+        const child = spawn(editor, args, { stdio: 'inherit' });
+        child.on('close', () => {
+            console.log(chalk.dim(`\n  Saved to ${CONFIG_PATH}`));
+        });
+        return;
+    }
+    console.log(chalk.red(`  Unknown config subaction: ${subAction}`));
+    console.log(chalk.dim(`  Try: path, show, edit`));
+}
+// ─── helpers ───────────────────────────────────────────────────────────────
+function runChild(cmd, args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(cmd, args, { stdio: 'inherit' });
+        child.on('close', (code) => {
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(`${cmd} ${args.join(' ')} exited with code ${code}`));
+        });
+        child.on('error', reject);
+    });
+}

package/dist/index.js

@@ -111,13 +111,33 @@ program
     const matches = searchSessions(query, { limit, model: opts.model });
     process.stdout.write(formatSearchResults(matches, query));
 });
+// ─── franklin social (native X bot) ───────────────────────────────────────
+// First-class subcommand. Handles setup / login / run / stats / config
+// subactions. No plugin SDK, no MCP — everything lives in src/social/.
+program
+    .command('social [action] [arg]')
+    .description('Native X bot — franklin social setup | login x | run | stats | config')
+    .option('--dry-run', 'Generate drafts without posting (default for run)')
+    .option('--live', 'Actually post to X (overrides dry-run default)')
+    .option('-m, --model <model>', 'Override the model used for reply generation')
+    .option('--debug', 'Enable debug logging')
+    .action(async (action, arg, opts) => {
+    const { socialCommand } = await import('./commands/social.js');
+    await socialCommand(action, arg, opts);
+});
 // Plugin commands — dynamically registered from discovered plugins.
 // Core stays plugin-agnostic: this loop adds a command for each installed plugin.
+// Note: `social` is now a first-class native command above and NOT loaded as a
+// plugin (the bundled social plugin was retired in v3.2.0 in favour of the
+// src/social/ subsystem).
 {
     const { loadAllPlugins, listWorkflowPlugins } = await import('./plugins/registry.js');
     await loadAllPlugins();
     for (const lp of listWorkflowPlugins()) {
         const { manifest } = lp;
+        // Skip any plugin whose id collides with a built-in command (e.g. social)
+        if (manifest.id === 'social')
+            continue;
         program
             .command(`${manifest.id} [action]`)
             .description(manifest.description)

package/dist/social/a11y.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Helpers for finding elements in the flat [depth-idx] ref tree produced by
+ * SocialBrowser.snapshot(). Ported from social-bot's bot/browser.py regex
+ * model, where elements are located by role + label rather than CSS/XPath.
+ *
+ * The mental model: snapshot() returns a string like
+ *
+ *   [0-0] main: Timeline
+ *     [1-0] article: post by user
+ *       [2-0] link: Mar 16
+ *       [2-1] StaticText: hello world
+ *     [1-1] button: Reply
+ *     [1-2] textbox: Post text
+ *
+ * …and these helpers find the refs via regex on that string.
+ */
+/**
+ * Find all refs matching a role and a label pattern.
+ *
+ * @param tree    The snapshot output string
+ * @param role    AX role, e.g. "button", "link", "textbox", "article"
+ * @param label   Regex source for the label (default `.*` — any). Substring matches count.
+ * @returns       Array of ref ids like ["0-0", "1-3"] in document order
+ */
+export declare function findRefs(tree: string, role: string, label?: string): string[];
+/**
+ * Find refs AND their labels. Useful when you want both the click target
+ * (ref) and the visible text (label) in one pass.
+ */
+export declare function findRefsWithLabels(tree: string, role: string, label?: string): Array<{
+    ref: string;
+    label: string;
+}>;
+/**
+ * Find text content inside the tree (not a ref — just the visible string).
+ * Useful for reading static text like tweet snippets.
+ */
+export declare function findStaticText(tree: string): string[];
+/**
+ * Split an X timeline/search snapshot into per-article blocks so we can
+ * process each tweet independently. Returns the text slice for each article,
+ * starting at the `[N-M] article:` line and ending at the next article or
+ * end-of-tree.
+ */
+export declare function extractArticleBlocks(tree: string): Array<{
+    ref: string;
+    text: string;
+}>;
+/**
+ * Regex pattern for X's "time-link" text: "Mar 16", "5h", "just now", "2d", etc.
+ * This doubles as the "this is a tweet" signal in social-bot — the only link
+ * inside an article block with this label shape is the permalink to the tweet.
+ */
+export declare const X_TIME_LINK_PATTERN = "(?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)\\s+\\d+|\\d+[smhd]|just now|now";

package/dist/social/a11y.js

@@ -0,0 +1,89 @@
+/**
+ * Helpers for finding elements in the flat [depth-idx] ref tree produced by
+ * SocialBrowser.snapshot(). Ported from social-bot's bot/browser.py regex
+ * model, where elements are located by role + label rather than CSS/XPath.
+ *
+ * The mental model: snapshot() returns a string like
+ *
+ *   [0-0] main: Timeline
+ *     [1-0] article: post by user
+ *       [2-0] link: Mar 16
+ *       [2-1] StaticText: hello world
+ *     [1-1] button: Reply
+ *     [1-2] textbox: Post text
+ *
+ * …and these helpers find the refs via regex on that string.
+ */
+/**
+ * Find all refs matching a role and a label pattern.
+ *
+ * @param tree    The snapshot output string
+ * @param role    AX role, e.g. "button", "link", "textbox", "article"
+ * @param label   Regex source for the label (default `.*` — any). Substring matches count.
+ * @returns       Array of ref ids like ["0-0", "1-3"] in document order
+ */
+export function findRefs(tree, role, label = '.*') {
+    const re = new RegExp(`\\[(\\d+-\\d+)\\]\\s+${escapeRegex(role)}:\\s*${label}`, 'g');
+    const out = [];
+    let m;
+    while ((m = re.exec(tree)) !== null) {
+        out.push(m[1]);
+    }
+    return out;
+}
+/**
+ * Find refs AND their labels. Useful when you want both the click target
+ * (ref) and the visible text (label) in one pass.
+ */
+export function findRefsWithLabels(tree, role, label = '.*') {
+    const re = new RegExp(`\\[(\\d+-\\d+)\\]\\s+${escapeRegex(role)}:\\s*(${label})`, 'g');
+    const out = [];
+    let m;
+    while ((m = re.exec(tree)) !== null) {
+        out.push({ ref: m[1], label: m[2].trim() });
+    }
+    return out;
+}
+/**
+ * Find text content inside the tree (not a ref — just the visible string).
+ * Useful for reading static text like tweet snippets.
+ */
+export function findStaticText(tree) {
+    const re = /\[\d+-\d+\]\s+StaticText:\s*(.+)/g;
+    const out = [];
+    let m;
+    while ((m = re.exec(tree)) !== null) {
+        out.push(m[1].trim());
+    }
+    return out;
+}
+/**
+ * Split an X timeline/search snapshot into per-article blocks so we can
+ * process each tweet independently. Returns the text slice for each article,
+ * starting at the `[N-M] article:` line and ending at the next article or
+ * end-of-tree.
+ */
+export function extractArticleBlocks(tree) {
+    const articleStarts = [];
+    const re = /\[(\d+-\d+)\]\s+article:/g;
+    let m;
+    while ((m = re.exec(tree)) !== null) {
+        articleStarts.push({ ref: m[1], pos: m.index });
+    }
+    const out = [];
+    for (let i = 0; i < articleStarts.length; i++) {
+        const start = articleStarts[i].pos;
+        const end = i + 1 < articleStarts.length ? articleStarts[i + 1].pos : tree.length;
+        out.push({ ref: articleStarts[i].ref, text: tree.slice(start, end) });
+    }
+    return out;
+}
+/**
+ * Regex pattern for X's "time-link" text: "Mar 16", "5h", "just now", "2d", etc.
+ * This doubles as the "this is a tweet" signal in social-bot — the only link
+ * inside an article block with this label shape is the permalink to the tweet.
+ */
+export const X_TIME_LINK_PATTERN = '(?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)\\s+\\d+|\\d+[smhd]|just now|now';
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}