feat(onboarding): 移植认领链接引导与零配置文案 (#3)

将 claude-code 插件已合并的 onboarding UX 改进移植到 antigravity 端：
- session-start.js：新增 CLAIM_TTL_MS 与 readPendingClaimUrl(),读取
  ~/.evomap/claim_url 后一次性(12h 节流、fail-closed)提示去 evomap.ai
  认领本地已注册但未连网的 node,复用既有 throttled() 基建。
- README.md：安装小节点明本地记忆零配置可用,新增 "Connecting to the
  EvoMap network (optional)" 三步(留空 Node ID → 跑 evolver → 认领链接),
  并在 hooks 说明表补充 session-start 的一次性认领提示。
- evolver-status 技能:补充 claim_url 未认领与 HTTP 402/credits 的平白话
  说明,避免直接甩 JSON / node_secret / stake / hub_rotate。
- CHANGELOG.md:新增 [Unreleased] → Changed — onboarding UX,不 bump 版本。

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

Author: autogame-17

CHANGELOG.md

@@ -3,6 +3,22 @@
 All notable changes to the Evolver Antigravity Desktop plugin are documented here.
 This project adheres to [Semantic Versioning](https://semver.org/).
 
+## [Unreleased]
+
+### Changed — onboarding UX
+- README: the Installation 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). The
+  `session-start.js` hook row now mentions the one-time claim nudge.
+- `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` skill now translates connection state into plain "are you
+  connected?" language — surfacing the pending claim link and explaining HTTP
+  402 as "network features need credits" (https://evomap.ai/pricing) instead of
+  dumping raw JSON or internal terms like `node_secret` / `stake`.
+
 ## [0.1.1] — 2026-06-25
 
 ### Fixed

README.md

@@ -20,7 +20,7 @@ Three lifecycle hooks run automatically on events and require no configuration o
 
 | Hook | Event | Effect |
 |---|---|---|
-| `session-start.js` | `PreInvocation` | Injects a summary of recent **successful** outcomes for this workspace (score ≥ 0.5, < 7 days, max 3) as an ephemeral model context step. |
+| `session-start.js` | `PreInvocation` | Injects a summary of recent **successful** outcomes for this workspace (score ≥ 0.5, < 7 days, max 3) as an ephemeral model context step. When a node has been registered locally but not yet connected to the network, it also gives a one-time (throttled) nudge to claim it. |
 | `signal-detect.js` | `PostToolUse` | Detects improvement signals (`log_error`, `perf_bottleneck`, `capability_gap`, `test_failure` ...) in tool outputs or edits and exits cleanly under Antigravity's PostToolUse contract. |
 | `session-end.js` | `Stop` | Classifies the current working-tree/staged git diff once per session and appends the outcome to the evolution memory graph. |
 
@@ -76,6 +76,29 @@ If `~/.gemini/config/mcp_config.json` exists, it must contain valid JSON, for ex
 }
 ```
 
+After installing, 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 the `evolver-status` skill.
+
+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.
+
 ---
 
 ## Requirements

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.
@@ -243,6 +264,23 @@ function main(input) {
     // 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);

skills/evolver-status/SKILL.md

@@ -36,4 +36,13 @@ When requested by the user, run the following diagnostic checks using shell/term
    command -v evolver >/dev/null 2>&1 && evolver --version 2>/dev/null | head -1 || echo "evolver CLI not installed — hooks still work standalone; 'npm i -g @evomap/evolver' unlocks full pipeline features"
    ```
 
+5. **Network connection (optional)** — check whether a node has been registered locally but not yet claimed on the network:
+
+   ```bash
+   C=~/.evomap/claim_url
+   [ -s "$C" ] && echo "not connected yet — claim this node by opening $(cat "$C") while signed in to evomap.ai (that is the only step; no id or secret to enter)" || echo "no pending claim (either not registered yet, or already connected)"
+   ```
+
+   If the Proxy is reachable and `evolver_status` reports an HTTP **402 / insufficient credits**, translate that for the user in plain language: the network features (searching/reusing genes & capsules) need credits — see https://evomap.ai/pricing — while local evolution memory keeps working exactly as before. When reporting connection state, keep it to plain "are you connected?" language: surface the claim link and the credits note as above; do **not** dump raw JSON or internal terms like `node_secret`, `stake`, or `hub_rotate`.
+
 Finish with a single-line summary statement on the overall readiness of the self-evolution memory.