feat(onboarding): 把入门体验反向做顺，突出 node_id 留空为正道 (#6)

从插件侧重做首次配置体验：核心信息是「node_id 留空才是正道」——不用
找旧 node、不用 secret，首次运行自动注册并给一条认领链接，点它认领即可。

- plugin.json: node_id 文案改为「leave blank for automatic setup」，
  描述说明首次运行自动注册 + 打印认领链接，绝不粘 id/secret。
- README: Install 段点明本地记忆零配置可用；新增
  「Connecting to the EvoMap network (optional)」三步指引
  （留空 → 跑 evolver → 认领链接），并说明复用旧 node 才需 secret、更麻烦。
- session-start.js: 有本地已注册但未连接网络的 node 时，一次性(12h 节流)
  提示去认领；读 ~/.evomap/claim_url，fail-closed。
- /evolver:status: 把 Proxy 状态翻成平白话「你连上了没」，surface 认领链接、
  把 402 说成「网络功能需要 credits」，不甩原始 JSON / node_secret / stake。
- CHANGELOG: 新增 [Unreleased] → Changed — onboarding UX（不 bump 版本）。

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: autogame-17

.claude-plugin/plugin.json

@@ -22,8 +22,8 @@
   "userConfig": {
     "node_id": {
       "type": "string",
-      "title": "EvoMap Node ID (A2A_NODE_ID)",
-      "description": "Your EvoMap node identity. Leave blank to let the Proxy register one on first run.",
+      "title": "EvoMap Node ID — leave blank for automatic setup",
+      "description": "Leave this blank (recommended). On first run the local Proxy registers a fresh node for you and prints a link to claim it on evomap.ai — you never paste an id or a secret here. Only fill this in to point the install at a node you already run yourself.",
       "default": ""
     },
     "hub_url": {

CHANGELOG.md

@@ -3,6 +3,25 @@
 All notable changes to the Evolver Claude Code plugin are documented here.
 This project adheres to [Semantic Versioning](https://semver.org/).
 
+## [Unreleased]
+
+### Changed — onboarding UX
+- `node_id` config field reworded to make **leaving it blank** the clear default:
+  the title now reads "leave blank for automatic setup" and the description
+  explains that the first run registers a fresh node and prints a claim link —
+  no id or secret to paste.
+- README: the Install section now states that local memory works with zero
+  config, and a new **"Connecting to the EvoMap network (optional)"** section
+  walks through the blank-node-id → `evolver` → claim-link flow (and notes that
+  reusing a specific older node is the harder, secret-requiring path).
+- `session-start.js` gives a one-time, throttled nudge to claim the node when
+  one has been registered locally (`~/.evomap/claim_url`) but not yet connected
+  to the network (fail-closed, 12h throttle).
+- `/evolver:status` now translates Proxy state into plain "are you connected?"
+  language — surfacing the pending claim link and explaining HTTP 402 as
+  "network features need credits" instead of dumping raw JSON or internal terms
+  like `node_secret` / `stake`.
+
 ## [0.2.2] — 2026-06-25
 
 ### Fixed

README.md

@@ -25,7 +25,7 @@ Three hooks run automatically — you don't invoke them:
 
 | Hook | Event | Effect |
 |---|---|---|
-| `session-start.js` | `SessionStart` | Injects a summary of recent **successful** outcomes for this workspace (score ≥ 0.5, < 7 days, max 3) as context. |
+| `session-start.js` | `SessionStart` | Injects a summary of recent **successful** outcomes for this workspace (score ≥ 0.5, < 7 days, max 3) as context. Also, when a node has been registered locally but not yet connected to the network, gives a one-time (throttled) nudge to claim it. |
 | `signal-detect.js` | `PostToolUse` (Write/Edit) | Detects improvement signals (`log_error`, `perf_bottleneck`, `capability_gap`, …) in edits. |
 | `session-end.js` | `Stop` | Classifies the current working-tree/staged git diff once per session and appends the outcome to the evolution memory graph. |
 
@@ -56,8 +56,29 @@ and — when `@evomap/evolver` is installed — **`/evolver:run`**, **`/evolver:
 /plugin install evolver@evolver
 ```
 
-Restart Claude Code (or `/reload-plugins`). Set the EvoMap node id / hub / proxy
-port in the plugin's config if you use the MCP tools.
+Restart Claude Code (or `/reload-plugins`). That's it — **local memory works
+with zero config**: no account, no key, nothing to fill in.
+
+### Connecting to the EvoMap network (optional)
+
+The network layer (searching/reusing genes & capsules) is opt-in. To connect:
+
+1. In the plugin's config, **leave "Node ID" blank**. Don't paste an old id and
+   don't go hunting for a secret — blank is the intended path.
+2. Install the engine and run it once inside a git repo:
+
+   ```bash
+   npm i -g @evomap/evolver
+   evolver
+   ```
+
+   The first run registers a fresh node for you and prints a **claim link**.
+3. Open that link while signed in to [evomap.ai](https://evomap.ai) to claim the
+   node. Check status any time with `/evolver:status`.
+
+If you see a different, older node than you expected, don't worry about it —
+just claim the current one. Reusing a specific older node requires that node's
+secret, which is more trouble than it's worth.
 
 ### Local development
 

commands/status.md

@@ -11,6 +11,22 @@ Report Evolver health as a short checklist.
    starts when you run `evolver` once in a git repo, and that the local memory
    hooks keep working regardless.
 
+   Then translate the Proxy state into plain "are you connected?" language for
+   the user — **don't** dump raw error JSON or internal terms like
+   `node_secret`, `stake`, or `hub_rotate`:
+
+   - If `~/.evomap/claim_url` exists, the node is registered but **not yet
+     claimed**. Tell the user to sign in to evomap.ai and open that URL to
+     finish connecting — that's the only step, with no id or secret to find.
+
+     ```bash
+     [ -f ~/.evomap/claim_url ] && echo "not yet connected — sign in to evomap.ai and open: $(cat ~/.evomap/claim_url)" || echo "no pending claim link"
+     ```
+
+   - If a network call reports `insufficient credits` / HTTP 402, say plainly
+     that the network features need credits (buy or subscribe at
+     https://evomap.ai/pricing); local memory keeps working as usual.
+
 2. **Evolution memory** — does the local graph exist and how many outcomes?
 
 ```bash

hooks/session-start.js

@@ -25,6 +25,7 @@ const { filterRelevant } = require('./_filter');
 const MAX_SCAN_ENTRIES = 5; // how many workspace-matched entries to gather
 const LINE_MAX = 200; // per-outcome line truncation
 const NONGIT_TTL_MS = 30 * 60 * 1000; // throttle the non-git notice
+const CLAIM_TTL_MS = 12 * 60 * 60 * 1000; // throttle the pending-claim nudge
 const THROTTLE_PRUNE_MS = 24 * 60 * 60 * 1000;
 
 const NONGIT_NOTICE =
@@ -104,6 +105,26 @@ function throttled(key, ttlMs) {
   }
 }
 
+/**
+ * Read a pending claim URL left by the engine. When the engine registers a
+ * fresh node that hasn't been claimed on evomap.ai yet, it writes the claim
+ * link to `~/.evomap/claim_url`; it clears that file once the node is claimed.
+ * Returns the trimmed url if it looks like an http(s) link, else null.
+ * Fails closed (null) on any error — the nudge is optional.
+ */
+function readPendingClaimUrl() {
+  try {
+    const file = path.join(os.homedir(), '.evomap', 'claim_url');
+    const url = fs.readFileSync(file, 'utf8').trim();
+    if (/^https?:\/\//.test(url)) {
+      return url;
+    }
+    return null;
+  } catch (_err) {
+    return null;
+  }
+}
+
 /**
  * Decide whether a memory entry belongs to the current workspace.
  *   - tagged with workspace_id, our id known: match iff equal.
@@ -234,6 +255,23 @@ function main() {
     // ignore — notice is optional
   }
 
+  // 1b. Pending-claim nudge (throttled per claim url).
+  try {
+    const claimUrl = readPendingClaimUrl();
+    if (claimUrl && !throttled(`claim:${claimUrl}`, CLAIM_TTL_MS)) {
+      parts.push(
+        '[Evolver] Your local node is not connected to the EvoMap network ' +
+          'yet. To finish connecting, open ' +
+          claimUrl +
+          ' while signed in to evomap.ai — that is the only step, with no id ' +
+          'or secret to enter. Local evolution memory already works without ' +
+          'this; connecting only adds the network gene/capsule tools.'
+      );
+    }
+  } catch (_err) {
+    // ignore — nudge is optional
+  }
+
   // 2. Workspace-scoped evolution memory.
   try {
     const graphPath = findMemoryGraph(currentDir);