skalpel 3.2.5 → 3.2.7

package/INSTALL.md

@@ -47,7 +47,28 @@ Post-W4 (OAuth port): first run is a guided TUI walkthrough plus browser-loopbac
 
 This flow corresponds to Journey 1 — First launch, fresh authentication — in `SPEC.md`. That narrative describes what the user feels at each step; this document describes what the install machinery actually does.
 
-If the user runs `skalpel` without first running `skalpel login`, the walkthrough prompts them to sign in inline (Enter), skip for now (`s`), turn interception off (`o`), or quit (`q`). To sign out of an existing account on this machine, run `skalpel logout` from a shell — the CLI revokes the backend session (best-effort) and removes `auth.json` via `internal/auth.Delete`.
+If the user runs `skalpel` without first running `skalpel login`, the walkthrough prompts them to sign in inline (Enter), skip for now (`s`), turn interception off (`o`), or quit (`q`). The walkthrough also surfaces the website onboarding URL (`https://launch.skalpel.ai/signup`) and notes that a wizard activation command can be pasted directly — npm frequently hides `postinstall` output, so this CLI-side hint is where self-serve `npm install -g` users reliably learn how to activate. To sign out of an existing account on this machine, run `skalpel logout` from a shell — the CLI revokes the backend session (best-effort) and removes `auth.json` via `internal/auth.Delete`.
+
+### Guided activation vs. self-serve global install
+
+The primary, guided path is the website signup wizard, which mints a one-time, version-pinned-to-`latest` command:
+
+```bash
+npx --yes skalpel@<latest> login --activation <token>
+```
+
+`login --activation` is **auth-only**: it claims the token, writes `auth.json`, prints a next-step hint, and exits without launching the TUI (the magic flow is a deliberate terminal handoff). Browser-loopback `skalpel login` is unchanged and still lands the user on the dashboard.
+
+A user who independently runs `npm install -g skalpel` is still supported: `postinstall` prints a best-effort pointer to `https://launch.skalpel.ai/signup`, and the first `skalpel` run repeats that pointer where output is guaranteed.
+
+### `skalpel setup` — detect and wrap coding agents
+
+After authentication, `skalpel setup` detects which coding-agent harnesses are installed (cross-platform on Linux, Windows, and macOS) via PATH and per-user config probes:
+
+- **Claude Code** and **Codex CLI** — detected and wrappable.
+- **Cursor** — detected for display only (no Skalpel wrapper today).
+
+The user opts into which detected agents to wrap. `setup` resolves the correct shell startup file for the current OS + shell (zsh/bash/fish rc files, or the PowerShell `$PROFILE` on Windows), writes a managed fenced block (identical fences to the install-time block, so `skalpel uninstall` removes either), and prints exactly which file changed plus undo instructions (`skalpel uninstall`, or `SKALPEL_NO_AGENT_WRAP=1` to disable wrapping). It never launches the TUI. On an unknown OS/shell it prints manual instructions instead of writing.
 
 Historical note: prior versions of skalpel supported pasting a `sk-skalpel-*` API key copied from the web dashboard as an alternative to `skalpel login`. The W4 OAuth-port grep-delete removed both the api_key-paste wizard and the daemon-side api_key sending path. Users on stale auth.json files (api_key-only, no Cognito bundle) need to run `skalpel login` once to refresh.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skalpel",
-  "version": "3.2.5",
+  "version": "3.2.7",
   "description": "Skalpel — local proxy and TUI for coding agents (skalpel + skalpeld bundle).",
   "license": "Apache-2.0",
   "homepage": "https://skalpel.ai",
@@ -58,10 +58,10 @@
     "x64"
   ],
   "optionalDependencies": {
-    "@skalpelai/skalpel-darwin-arm64": "3.2.5",
-    "@skalpelai/skalpel-darwin-x64": "3.2.5",
-    "@skalpelai/skalpel-linux-arm64": "3.2.5",
-    "@skalpelai/skalpel-linux-x64": "3.2.5",
-    "@skalpelai/skalpel-win32-x64": "3.2.5"
+    "@skalpelai/skalpel-darwin-arm64": "3.2.7",
+    "@skalpelai/skalpel-darwin-x64": "3.2.7",
+    "@skalpelai/skalpel-linux-arm64": "3.2.7",
+    "@skalpelai/skalpel-linux-x64": "3.2.7",
+    "@skalpelai/skalpel-win32-x64": "3.2.7"
   }
 }

package/postinstall/lib/launch.js

@@ -15,16 +15,24 @@
 const path = require('path');
 const log = require('./log');
 
+// ONBOARDING_URL is the canonical first-run destination. The guided
+// product flow is the website signup wizard (which mints a one-time
+// activation command), not `npm install -g`. We surface it here so a
+// self-serve global install still has a clean path to activation.
+const ONBOARDING_URL = 'https://launch.skalpel.ai/signup';
+
 function run({ dryRun }) {
-  const hint =
-    'all set — run `skalpel` to open the guided TUI walkthrough (sign-in, daemon status, toggle tips)';
+  const hint = `next: activate your account at ${ONBOARDING_URL}`;
   if (dryRun) {
     log.dryRun(`step 5 launch: would print: ${hint}`);
     return { launched: false, dryRun: true };
   }
+  // Minimal, best-effort onboarding pointer. npm frequently hides
+  // postinstall output, so the CLI's first-run gate repeats this hint
+  // (see cmd/skalpel/signin_gate.go) where output is guaranteed.
   log.info(hint);
-  log.info('npm may hide lifecycle output by default; use `npm install -g skalpel --foreground-scripts` if you want to see wizard logs.');
-  return { launched: false, deferred: true };
+  log.info('already have a wizard command? paste it in your terminal, or run `skalpel login`.');
+  return { launched: false, deferred: true, onboardingUrl: ONBOARDING_URL };
 }
 
 module.exports = { run };