sverklo 0.28.3 → 0.29.1

package/README.md

@@ -15,14 +15,17 @@ Sverklo gives coding agents repo memory: symbols, callers, diffs, blast radius,
 Use grep when you know the exact string. Use Sverklo when the agent needs relationships: who calls this, what depends on it, what changed, and which project decisions still apply. The public bench covers 180 hand-verified tasks across 6 OSS codebases; the methodology and ground truth live in [sverklo/sverklo-bench](https://github.com/sverklo/sverklo-bench). [Bench](https://sverklo.com/bench/) · [paper](https://doi.org/10.5281/zenodo.19802051) · [90-second demo](https://www.youtube.com/watch?v=OX7aEgdlqhQ)
 
 ```bash
-npm install -g sverklo
-cd your-project && sverklo init
-sverklo prove
+cd your-project
+npm exec --yes --package=sverklo@latest -- sverklo prove --no-write --guided
+sverklo init --dry-run
+npm install -g sverklo && sverklo init
 ```
 
-`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.
+`sverklo prove --no-write --guided` shows central files, a real symbol with callers, why that proof was selected, and the exact prompt to paste into your agent before any MCP config or instruction files are written. It may cache the local model/index under `~/.sverklo`, but it does not mutate your project. `sverklo init --dry-run` then previews the files `init` would touch; `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. Your code stays on your machine.
 
-Need something shareable? Run `sverklo prove --markdown` to print a GitHub/Discord-ready proof receipt from your repo.
+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
 >
@@ -75,12 +78,13 @@ Sverklo drills into your repo before the agent does — symbol graph, blast radi
 </table>
 
 ```bash
-npm install -g sverklo
-cd your-project && sverklo init
-sverklo prove
+cd your-project
+npm exec --yes --package=sverklo@latest -- sverklo prove --no-write --guided
+sverklo init --dry-run
+npm install -g sverklo && sverklo init
 ```
 
-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. Works on macOS, Linux, and Windows. **No API keys. No cloud. Telemetry off by default.**
+That's it. `sverklo prove --no-write --guided` gives you the first useful repo-memory proof from your own codebase before project config changes; `sverklo init --dry-run` previews every setup target; `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 --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.
 
@@ -449,12 +453,13 @@ Click the badge for your editor. Cursor / VS Code prompt to confirm, then sverkl
 <br/>
 
 ```bash
-npm install -g sverklo
-cd your-project && sverklo init
-sverklo prove
+cd your-project
+npm exec --yes --package=sverklo@latest -- sverklo prove --no-write --guided
+sverklo init --dry-run
+npm install -g sverklo && sverklo init
 ```
 
-`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. Idempotent — safe to re-run. If sverklo doesn't appear in your agent after restart, run `sverklo doctor`.
+Start with proof, then wire the agent. `sverklo prove --no-write --guided` prints central files, a real caller graph, why that symbol was selected, and a prompt to paste into your agent without writing MCP config or instruction files. `sverklo init --dry-run` previews setup targets. `sverklo init` auto-detects which AI coding agents you have (Claude Code, Cursor, Windsurf, Zed, Antigravity) and writes the right MCP config files. 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 --agent claude` or the matching agent name.
 
 **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

@@ -39,6 +39,8 @@ async function resolveProjectPath(flags) {
 }
 function parseProveArgs(rawArgs) {
     let format = "text";
+    let guided = false;
+    let noWrite = false;
     const pathArgs = [];
     for (let i = 0; i < rawArgs.length; i++) {
         const arg = rawArgs[i];
@@ -65,9 +67,17 @@ function parseProveArgs(rawArgs) {
             format = value === "markdown" ? "markdown" : "text";
             continue;
         }
+        if (arg === "--guided") {
+            guided = true;
+            continue;
+        }
+        if (arg === "--no-write" || arg === "--no-config-write") {
+            noWrite = true;
+            continue;
+        }
         pathArgs.push(arg);
     }
-    return { format, pathArgs };
+    return { format, guided, noWrite, pathArgs };
 }
 // Global --help / -h interceptor.
 //
@@ -102,6 +112,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).",
@@ -149,6 +160,137 @@ 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 cycleNow = trends?.captured_at ??
+                profile?.captured_at ??
+                recentPosts?.captured_at ??
+                existing?.updated_at;
+            const cycle = runCampaignCycle({
+                workspace,
+                existingCycle: existing,
+                trendSnapshot: trends,
+                profileSnapshot: profile,
+                recentPosts,
+                evidence,
+                cycleId: flagVal("--cycle"),
+                now: cycleNow,
+            });
+            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("--"));
@@ -156,7 +298,18 @@ if (command === "init") {
     const autoCapture = flags.includes("--auto-capture");
     const mineChats = flags.includes("--mine-chats");
     const isGlobal = flags.includes("--global");
+    const dryRun = flags.includes("--dry-run");
     const projectPath = resolve(positional[1] || process.cwd());
+    if (dryRun) {
+        if (isGlobal) {
+            console.error("✗ sverklo init --dry-run does not support --global yet");
+            console.error("  Run `sverklo init --global` only after reviewing global instruction targets manually.");
+            process.exit(2);
+        }
+        const { renderInitDryRun } = await import("../src/init.js");
+        process.stdout.write(renderInitDryRun(projectPath, { autoCapture, mineChats }));
+        process.exit(0);
+    }
     if (isGlobal) {
         // Issue #72 — one-time-per-machine setup. Writes SVERKLO_SNIPPET to
         // global agent-instruction locations (~/.claude/CLAUDE.md, ~/.codex/AGENTS.md),
@@ -195,10 +348,10 @@ if (command === "register") {
     process.exit(0);
 }
 if (command === "prove") {
-    const { format, pathArgs } = parseProveArgs(args.slice(1));
+    const { format, guided, noWrite, pathArgs } = parseProveArgs(args.slice(1));
     const projectPath = await resolveProjectPath(pathArgs);
     const { runProve } = await import("../src/prove.js");
-    const report = await runProve(projectPath, { format });
+    const report = await runProve(projectPath, { format, guided, noWrite });
     process.stdout.write(report);
     process.exit(0);
 }
@@ -523,9 +676,24 @@ if (command === "audit-prompt" || command === "review-prompt") {
     process.exit(0);
 }
 if (command === "doctor" || command === "diagnose" || command === "check") {
-    const projectPath = resolve(args[1] || process.cwd());
+    let agent;
+    const pathArgs = [];
+    for (let i = 1; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--agent") {
+            agent = args[i + 1];
+            i++;
+            continue;
+        }
+        if (arg.startsWith("--agent=")) {
+            agent = arg.slice("--agent=".length);
+            continue;
+        }
+        pathArgs.push(arg);
+    }
+    const projectPath = resolve(pathArgs[0] || process.cwd());
     const { runDoctor } = await import("../src/doctor.js");
-    runDoctor(projectPath);
+    runDoctor(projectPath, { agent });
     process.exit(0);
 }
 if (command === "workspace") {
@@ -2612,16 +2780,21 @@ if (command === "--help" || command === "-h") {
 sverklo — code intelligence for AI agents
 
 Just installed? Run these two:
-  sverklo init               Set up sverklo in your project (.mcp.json + CLAUDE.md)
-  sverklo prove              Show a real repo-memory proof from your codebase
+  sverklo prove --no-write --guided
+                             Show proof before writing project or agent config files
+  sverklo init --dry-run     Preview the config files init would touch
 
 Then restart your AI agent (Claude Code, Cursor, Windsurf, etc.) — sverklo tools become available automatically.
 
 Usage:
   sverklo init               Set up sverklo in your project (.mcp.json + CLAUDE.md)
+  sverklo init --dry-run     Preview planned writes without changing files
   sverklo doctor             Diagnose MCP setup issues
+  sverklo doctor --agent codex
+                             Show agent-specific setup/check prompt guidance
   sverklo prove [path]       Show central files, a real caller graph, and an agent prompt
-                             Use --markdown or --receipt for a shareable artifact.
+                             Use --guided for selection notes, --no-write for trial mode,
+                             and --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.
@@ -2646,6 +2819,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)
@@ -2662,9 +2836,10 @@ Setup / runtime:
   sverklo --help             Show this help
 
 Quick start (single project):
-  npm install -g sverklo
-  cd your-project && sverklo init
-  sverklo prove
+  cd your-project
+  npm exec --yes --package=sverklo@latest -- sverklo prove --no-write --guided
+  sverklo init --dry-run
+  npm install -g sverklo && sverklo init
   sverklo prove --markdown  # shareable proof for GitHub, Discord, Reddit, etc.
   claude   # start coding — sverklo tools are preferred automatically