sverklo 0.29.0 → 0.29.2

package/README.md

@@ -12,17 +12,22 @@ Sverklo gives coding agents repo memory: symbols, callers, diffs, blast radius,
 
 **Local-first** ◦ MIT ◦ no API keys ◦ no code upload ◦ first run downloads a local ONNX model
 
-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)
+**Use Sverklo when** your agent needs relationships before editing: callers, dependencies, tests, diff risk, or prior repo decisions.
+
+**Use grep/ripgrep when** you know the exact string, the repo is tiny, or the change is one file.
+
+Start with the no-write proof command before installing MCP config. 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 --markdown
+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 --markdown` shows central files, a real symbol with callers, why that proof was selected, the exact prompt to paste into your agent, and a small feedback template 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, then [post it in the proof thread](https://github.com/sverklo/sverklo/discussions/79).
+Need something shareable? Run `sverklo prove --no-write --guided --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.
 
@@ -41,7 +46,7 @@ Need local launch planning for the Sverklo account? `sverklo marketing` runs a l
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.19802051.svg)](https://doi.org/10.5281/zenodo.19802051)
 [![GitHub stars](https://img.shields.io/github/stars/sverklo/sverklo?style=social)](https://github.com/sverklo/sverklo/stargazers)
 
-> If `sverklo prove` surfaces useful repo context, please star the repo. It is the fastest way to help other agent-heavy teams find it.
+> If `sverklo prove` surfaces useful repo context, please post a receipt, correction, grep-better case, or setup-friction report in [the proof thread](https://github.com/sverklo/sverklo/discussions/79). If it helped, starring the repo also helps other agent-heavy teams find it.
 
 ![Sverklo bench:primitives token comparison](./docs/hero-token-comparison.png)
 
@@ -77,12 +82,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 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.**
+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.
 
@@ -175,7 +181,7 @@ If the answer to your question is "exact string X exists somewhere," grep wins.
 | Tool | What it does |
 |------|-------------|
 | `search` | Hybrid BM25 + vector + PageRank search. Find code without knowing the literal string. |
-| `refs` | All references to a symbol, with caller context. Proves dead code with certainty. |
+| `refs` | All references to a symbol, with caller context. Flags likely dead-code candidates from the current reference graph. |
 | `impact` | Walk the symbol graph, return ranked transitive callers — the real blast radius. |
 | `review_diff` | Risk-scored review of `git diff`: touched-symbol importance x coverage x churn. |
 
@@ -451,12 +457,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, 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`.
+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.
 //
@@ -84,7 +94,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. Flags: --markdown, --receipt, --format text|markdown.",
+            prove: "Show a first-run repo-memory proof: central files, a real symbol with callers, and a paste-ready agent prompt. Flags: --no-write, --guided, --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.",
@@ -217,6 +227,10 @@ if (command === "marketing") {
             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,
@@ -225,6 +239,7 @@ if (command === "marketing") {
                 recentPosts,
                 evidence,
                 cycleId: flagVal("--cycle"),
+                now: cycleNow,
             });
             saveMarketingWorkspace(workspacePath, workspace);
             saveCampaignCycle(workspacePath, cycle);
@@ -283,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),
@@ -322,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);
 }
@@ -650,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") {
@@ -2739,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.
@@ -2790,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