sverklo 0.28.2 → 0.29.0

package/README.md

@@ -22,6 +22,10 @@ sverklo prove
 
 `sverklo init` writes the MCP config for your agent, appends local instructions to `AGENTS.md` or `CLAUDE.md`, and runs `sverklo doctor` to verify the handshake. `sverklo prove` then shows central files, a real symbol with callers, and the exact prompt to paste into your agent. Your code stays on your machine.
 
+Need something shareable? Run `sverklo prove --markdown` to print a GitHub/Discord-ready proof receipt from your repo, then [post it in the proof thread](https://github.com/sverklo/sverklo/discussions/79).
+
+Need local launch planning for the Sverklo account? `sverklo marketing` runs a local-first Twitter/X agent-team workflow from operator-provided snapshots. It ranks opportunities, drafts seed-content queues, checks profile health, and records human decisions without posting, scraping, replying, liking, reposting, following, or changing the profile.
+
 > *"The map is not the territory."* — Alfred Korzybski
 >
 > Training data is the map. Your codebase is the territory. **Sverklo gives the agent the territory.**
@@ -78,7 +82,7 @@ cd your-project && sverklo init
 sverklo prove
 ```
 
-That's it. `sverklo init` auto-detects your installed AI coding agent (Claude Code, Cursor, Windsurf, Zed), writes the right MCP config, appends instructions to `AGENTS.md` if present (otherwise `CLAUDE.md`), and runs `sverklo doctor` to verify the setup. `sverklo prove` shows the first useful repo-memory proof from your own codebase. Works on macOS, Linux, and Windows. **No API keys. No cloud. Telemetry off by default.**
+That's it. `sverklo init` auto-detects your installed AI coding agent (Claude Code, Cursor, Windsurf, Zed), writes the right MCP config, appends instructions to `AGENTS.md` if present (otherwise `CLAUDE.md`), and runs `sverklo doctor` to verify the setup. `sverklo prove` shows the first useful repo-memory proof from your own codebase; `sverklo prove --markdown` makes that proof shareable in [the public proof thread](https://github.com/sverklo/sverklo/discussions/79). Works on macOS, Linux, and Windows. **No API keys. No cloud. Telemetry off by default.**
 
 > The embedding model (`all-MiniLM-L6-v2` ONNX, ~86 MB) is downloaded from HuggingFace on first use into `~/.sverklo/models/` and cached forever — every subsequent run is fully offline.
 
@@ -452,7 +456,7 @@ cd your-project && sverklo init
 sverklo prove
 ```
 
-`sverklo init` auto-detects which AI coding agents you have (Claude Code, Cursor, Windsurf, Zed, Antigravity) and writes the right MCP config files. `sverklo prove` prints central files, a real caller graph, and a prompt to paste into your agent. Idempotent — safe to re-run. If sverklo doesn't appear in your agent after restart, run `sverklo doctor`.
+`sverklo init` auto-detects which AI coding agents you have (Claude Code, Cursor, Windsurf, Zed, Antigravity) and writes the right MCP config files. `sverklo prove` prints central files, a real caller graph, and a prompt to paste into your agent. Add `--markdown` or `--receipt` for a shareable proof artifact, then post it in [the proof thread](https://github.com/sverklo/sverklo/discussions/79). Idempotent — safe to re-run. If sverklo doesn't appear in your agent after restart, run `sverklo doctor`.
 
 **Per-agent config locations** (`sverklo init` writes these for you):
 - Claude Code: `.mcp.json` at project root + appends to `CLAUDE.md` (or `AGENTS.md` if present)

package/dist/bin/sverklo.js

@@ -37,6 +37,38 @@ async function resolveProjectPath(flags) {
     }
     return target;
 }
+function parseProveArgs(rawArgs) {
+    let format = "text";
+    const pathArgs = [];
+    for (let i = 0; i < rawArgs.length; i++) {
+        const arg = rawArgs[i];
+        if (arg === "--markdown" || arg === "--receipt") {
+            format = "markdown";
+            continue;
+        }
+        if (arg === "--format") {
+            const value = rawArgs[i + 1];
+            if (value !== "text" && value !== "plain" && value !== "markdown") {
+                console.error("✗ --format expects text, plain, or markdown");
+                process.exit(2);
+            }
+            format = value === "markdown" ? "markdown" : "text";
+            i++;
+            continue;
+        }
+        if (arg.startsWith("--format=")) {
+            const value = arg.slice("--format=".length);
+            if (value !== "text" && value !== "plain" && value !== "markdown") {
+                console.error("✗ --format expects text, plain, or markdown");
+                process.exit(2);
+            }
+            format = value === "markdown" ? "markdown" : "text";
+            continue;
+        }
+        pathArgs.push(arg);
+    }
+    return { format, pathArgs };
+}
 // Global --help / -h interceptor.
 //
 // Without this, `--help` falls through to whatever subcommand the user
@@ -52,7 +84,7 @@ if (command && command !== "--help" && command !== "-h") {
         const HELP_BLURBS = {
             init: "Set up sverklo in your project (.mcp.json + CLAUDE.md, auto-detects Claude Code/Cursor/Windsurf/Antigravity). With --global: one-time-per-machine setup — write SVERKLO_SNIPPET to ~/.claude/CLAUDE.md and ~/.codex/AGENTS.md, register the project, gitignore .sverklo/, import memories. Skips per-project boilerplate.",
             doctor: "Diagnose MCP setup issues. Run after `init` to verify the agent can reach sverklo.",
-            prove: "Show a first-run repo-memory proof: central files, a real symbol with callers, and a paste-ready agent prompt.",
+            prove: "Show a first-run repo-memory proof: central files, a real symbol with callers, and a paste-ready agent prompt. Flags: --markdown, --receipt, --format text|markdown.",
             audit: "Run codebase audit and emit a graded report. Flags: --format markdown|html|json|graph|arch|obsidian, --output PATH, --open, --badge, --publish.",
             "audit-diff": "Incremental architectural quality gate. Audits `git diff` for new cycles + fan-in spikes. Flags: --against REF, --fan-in-threshold N, --format human|json, --show-existing, --verbose. Exits 1 on regression.",
             review: "Risk-scored diff review (CI-friendly). Flags: --ref REF, --ci, --format markdown|json, --max-files N, --fail-on low|medium|high.",
@@ -70,6 +102,7 @@ if (command && command !== "--help" && command !== "-h") {
             digest: "5-line summary of what changed in this project. Flags: --since 7d, --format markdown|plain.",
             receipt: "Token-spend receipt for your recent Claude Code sessions. Shows where tokens went and projected yearly cost. Flags: --since 7d, --format plain|json.",
             memory: "Manage the memory store. Subcommands: show, edit, import, export.",
+            marketing: "Run the local-first Sverklo Twitter agent team workflow. Subcommands: init, run-cycle, decide, status.",
             grammars: "Manage tree-sitter grammars for the SVERKLO_PARSER=tree-sitter opt-in path. Subcommands: install.",
             weights: "Inspect .sverklo.yaml weight rules. Subcommands: explain <path> — show which glob matched and the effective weight.",
             "audit-prompt": "Print a ready-to-paste codebase-audit prompt (hybrid agent workflow).",
@@ -117,6 +150,132 @@ if (command === "--version" || command === "-v" || command === "-V") {
     console.log("sverklo (version unknown)");
     process.exit(0);
 }
+if (command === "marketing") {
+    const subcommand = args[1];
+    const flags = args.slice(2);
+    const flagVal = (name) => {
+        const idx = flags.indexOf(name);
+        if (idx !== -1 && flags[idx + 1])
+            return flags[idx + 1];
+        const prefixed = flags.find((f) => f.startsWith(`${name}=`));
+        return prefixed ? prefixed.slice(name.length + 1) : undefined;
+    };
+    const requireFlag = (name) => {
+        const value = flagVal(name);
+        if (!value) {
+            console.error(`✗ ${name} is required`);
+            process.exit(2);
+        }
+        return value;
+    };
+    const format = flagVal("--format") ?? "text";
+    if (format !== "text" && format !== "json") {
+        console.error(`✗ --format must be text or json, got "${format}"`);
+        process.exit(2);
+    }
+    const { appendOperatorDecision, applyOperatorDecision, assertEvidenceCatalog, assertProfileSnapshot, assertRecentPostsSnapshot, assertTrendSnapshot, buildStatusSummary, createOperatorDecision, initMarketingWorkspace, jsonFile, loadActiveCampaignCycle, loadCampaignCycle, loadMarketingWorkspace, marketingPaths, normalizeAccountHandle, recomputeCampaignReadiness, renderContentReport, renderOpportunityReport, renderProfileHealthReport, renderStatusText, resolveMarketingWorkspace, runCampaignCycle, saveCampaignCycle, saveMarketingWorkspace, writeReport, } = await import("../src/marketing/index.js");
+    const { existsSync } = await import("node:fs");
+    const { join } = await import("node:path");
+    const workspacePath = flagVal("--workspace");
+    const readOptional = (path) => {
+        return path && existsSync(path) ? jsonFile(path) : undefined;
+    };
+    if (!subcommand || subcommand === "--help" || subcommand === "-h") {
+        console.log(`\nsverklo marketing — local-first Twitter agent team workflow\n\n` +
+            `Usage:\n` +
+            `  sverklo marketing init --account @sverklo [--workspace PATH]\n` +
+            `  sverklo marketing run-cycle [--workspace PATH] [--trends PATH] [--profile PATH] [--recent-posts PATH] [--evidence PATH] [--format text|json]\n` +
+            `  sverklo marketing decide --target-type TYPE --target-id ID --decision VALUE [--reason TEXT] [--future]\n` +
+            `  sverklo marketing status [--workspace PATH] [--format text|json]\n\n` +
+            `No command posts to X/Twitter, scrapes X, sends DMs, likes, reposts, follows, unfollows, or mutates the profile.\n`);
+        process.exit(0);
+    }
+    try {
+        if (subcommand === "init") {
+            const account = normalizeAccountHandle(requireFlag("--account"));
+            const workspace = initMarketingWorkspace({ workspacePath, accountHandle: account });
+            console.log(`Initialized marketing workspace for ${workspace.account_handle} at ${resolveMarketingWorkspace(workspacePath)}`);
+            process.exit(0);
+        }
+        if (subcommand === "run-cycle") {
+            const workspace = loadMarketingWorkspace(workspacePath);
+            const root = resolveMarketingWorkspace(workspacePath);
+            const inputDir = marketingPaths(root).inputs;
+            const existing = loadActiveCampaignCycle(workspacePath, workspace);
+            const trends = readOptional(flagVal("--trends") ?? join(inputDir, "trend-snapshot.json"));
+            const profile = readOptional(flagVal("--profile") ?? join(inputDir, "profile-snapshot.json"));
+            const recentPosts = readOptional(flagVal("--recent-posts") ?? join(inputDir, "recent-posts.json"));
+            const evidence = readOptional(flagVal("--evidence") ?? join(inputDir, "evidence.json"));
+            if (trends)
+                assertTrendSnapshot(trends);
+            if (profile)
+                assertProfileSnapshot(profile);
+            if (recentPosts)
+                assertRecentPostsSnapshot(recentPosts);
+            if (evidence)
+                assertEvidenceCatalog(evidence);
+            if (!trends && !profile && !recentPosts && !evidence && !existing) {
+                throw new Error("no local marketing inputs found; provide --trends, --profile, --recent-posts, or --evidence");
+            }
+            const cycle = runCampaignCycle({
+                workspace,
+                existingCycle: existing,
+                trendSnapshot: trends,
+                profileSnapshot: profile,
+                recentPosts,
+                evidence,
+                cycleId: flagVal("--cycle"),
+            });
+            saveMarketingWorkspace(workspacePath, workspace);
+            saveCampaignCycle(workspacePath, cycle);
+            writeReport(workspacePath, cycle.cycle_id, "opportunities", renderOpportunityReport(cycle));
+            writeReport(workspacePath, cycle.cycle_id, "content", renderContentReport(cycle));
+            writeReport(workspacePath, cycle.cycle_id, "profile-health", renderProfileHealthReport(cycle));
+            const summary = buildStatusSummary(cycle);
+            if (format === "json")
+                console.log(JSON.stringify(summary, null, 2));
+            else
+                process.stdout.write(renderStatusText(summary));
+            process.exit(0);
+        }
+        if (subcommand === "decide") {
+            const workspace = loadMarketingWorkspace(workspacePath);
+            if (!workspace.active_cycle_id)
+                throw new Error("no active marketing cycle");
+            const cycle = loadCampaignCycle(workspacePath, workspace.active_cycle_id);
+            const decision = createOperatorDecision({
+                targetType: requireFlag("--target-type"),
+                targetId: requireFlag("--target-id"),
+                decision: requireFlag("--decision"),
+                reason: flagVal("--reason"),
+                future: flags.includes("--future"),
+            });
+            applyOperatorDecision(workspace, cycle, decision);
+            recomputeCampaignReadiness(cycle);
+            saveMarketingWorkspace(workspacePath, workspace);
+            saveCampaignCycle(workspacePath, cycle);
+            appendOperatorDecision(workspacePath, decision);
+            console.log(`Recorded decision ${decision.decision_id}`);
+            process.exit(0);
+        }
+        if (subcommand === "status") {
+            const workspace = loadMarketingWorkspace(workspacePath);
+            const cycle = loadActiveCampaignCycle(workspacePath, workspace);
+            const summary = buildStatusSummary(cycle);
+            if (format === "json")
+                console.log(JSON.stringify(summary, null, 2));
+            else
+                process.stdout.write(renderStatusText(summary));
+            process.exit(0);
+        }
+        console.error(`✗ unknown marketing subcommand: ${subcommand}`);
+        process.exit(2);
+    }
+    catch (err) {
+        console.error(`✗ ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(2);
+    }
+}
 if (command === "init") {
     // Parse flags: --auto-capture, --mine-chats, --global
     const flags = args.filter((a) => a.startsWith("--"));
@@ -163,10 +322,10 @@ if (command === "register") {
     process.exit(0);
 }
 if (command === "prove") {
-    const flags = args.slice(1);
-    const projectPath = await resolveProjectPath(flags);
+    const { format, pathArgs } = parseProveArgs(args.slice(1));
+    const projectPath = await resolveProjectPath(pathArgs);
     const { runProve } = await import("../src/prove.js");
-    const report = await runProve(projectPath);
+    const report = await runProve(projectPath, { format });
     process.stdout.write(report);
     process.exit(0);
 }
@@ -2589,6 +2748,7 @@ Usage:
   sverklo init               Set up sverklo in your project (.mcp.json + CLAUDE.md)
   sverklo doctor             Diagnose MCP setup issues
   sverklo prove [path]       Show central files, a real caller graph, and an agent prompt
+                             Use --markdown or --receipt for a shareable artifact.
   sverklo reindex [path]     Incremental rebuild of the index (changed files only)
                              Use --force to clear and rebuild from scratch.
                              Use --timing to see per-phase elapsed ms.
@@ -2613,6 +2773,7 @@ Memory + offline maintenance:
   sverklo wiki               Generate a markdown wiki from the indexed codebase
   sverklo digest             5-line summary of what changed in this project (--since 7d)
   sverklo memory export      Export memories to markdown / Notion / JSON
+  sverklo marketing          Local Sverklo Twitter agent team workflow
   sverklo grammars install   Install tree-sitter grammars for the v0.17 opt-in parser
   sverklo prune              Decay stale memories + consolidate similar episodic ones
   sverklo concept-index      Label clusters with an LLM (requires Ollama)
@@ -2632,6 +2793,7 @@ Quick start (single project):
   npm install -g sverklo
   cd your-project && sverklo init
   sverklo prove
+  sverklo prove --markdown  # shareable proof for GitHub, Discord, Reddit, etc.
   claude   # start coding — sverklo tools are preferred automatically
 
 Quick start (multi-repo, global):