sverklo 0.29.0 → 0.29.1

package/README.md

@@ -15,12 +15,13 @@ 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, then [post it in the proof thread](https://github.com/sverklo/sverklo/discussions/79).
 
@@ -77,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 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.
 
@@ -451,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, 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.
 //
@@ -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