From 3e0be312f8ad4ccdc2d3c26ec3c182675dcec682 Mon Sep 17 00:00:00 2001
From: KeiSei84 <2206745@gmail.com>
Date: Fri, 22 May 2026 19:38:22 +0800
Subject: [PATCH] feat(install): first-run /onboard nudge + normalize null hook
 matchers (#38)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

1. SessionStart hook first-run-onboard.sh: on first Claude Code session after
   install, nudges user/Claude to run `/onboard ~/Projects/*` (scan stack +
   create a project-specialist agent per project; delegates to /new-agent).
   Fires once (marker), then silent. Wired in settings-snippet under SessionStart.
2. lib-summary next-steps: lead with /onboard ~/Projects/*, then /new-agent.
3. lib-hooks merge: normalize null/absent matcher → "" (Claude Code /doctor
   rejects null; pre-kit hooks often lack a matcher field).

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 hooks/first-run-onboard.sh | 31 +++++++++++++++++++++++++++++++
 install/lib-hooks.sh       |  4 ++++
 install/lib-summary.sh     |  8 ++++++--
 settings-snippet.json      | 12 ++++++++++++
 4 files changed, 53 insertions(+), 2 deletions(-)
 create mode 100755 hooks/first-run-onboard.sh

diff --git a/hooks/first-run-onboard.sh b/hooks/first-run-onboard.sh
new file mode 100755
index 0000000..9e175ac
--- /dev/null
+++ b/hooks/first-run-onboard.sh
@@ -0,0 +1,31 @@
+#!/bin/sh
+# first-run-onboard — on the FIRST Claude Code session after a KeiSeiKit install,
+# nudge the user to scaffold a project-specialist agent for each of their
+# projects. Event: SessionStart (stdout is injected into the session context, so
+# Claude reads this and proactively offers /onboard). Fires ONCE: a marker is
+# written after the first display, then the hook is silent forever.
+# Bypass / reset: rm ~/.claude/.kei-firstrun-shown   (re-show on next session).
+
+MARKER="$HOME/.claude/.kei-firstrun-shown"
+[ -f "$MARKER" ] && exit 0
+# Only nudge when the agent fleet actually landed (a real install, not a stub).
+[ -d "$HOME/.claude/agents" ] || exit 0
+
+PROJ="$HOME/Projects"
+[ -d "$PROJ" ] || PROJ="$HOME/projects"
+[ -d "$PROJ" ] || PROJ="$HOME/Projects"   # fall back to the canonical name in the text
+
+cat <<EOF
+[KeiSeiKit first-run] The agent substrate is installed. Proactively offer the
+user a one-step project setup before anything else:
+
+  • Run  /onboard $PROJ/*   — scans every project, detects its stack, and
+    creates a tailored project-specialist agent for each (delegates to
+    /new-agent per project).
+  • Or   /new-agent         — create a single project-specialist agent.
+
+Suggest /onboard now unless the user declines.
+EOF
+
+: > "$MARKER"
+exit 0
diff --git a/install/lib-hooks.sh b/install/lib-hooks.sh
index 518c64e..98d375b 100644
--- a/install/lib-hooks.sh
+++ b/install/lib-hooks.sh
@@ -60,6 +60,10 @@ _jq_merge_hooks() {
     | reduce ($add.hooks | keys[]) as $phase ($orig;
         .hooks[$phase] = (
           ((.hooks[$phase] // []) + ($add.hooks[$phase] // []))
+          # Normalize null/absent matcher → "" (Claude Code /doctor rejects null;
+          # user's pre-kit hooks often have no matcher field). Before group_by so
+          # null + "" collapse into one group.
+          | map(.matcher //= "")
           | group_by(.matcher)
           | map(
               .[0].matcher as $m
diff --git a/install/lib-summary.sh b/install/lib-summary.sh
index 1d4e262..f5bbd47 100644
--- a/install/lib-summary.sh
+++ b/install/lib-summary.sh
@@ -66,7 +66,9 @@ print_summary() {
       $AGENTS_DIR/_assembler/target/release/assemble --validate
       ./install.sh --list   # show installed primitives
 
-  To create a new project-specialist agent:
+  To set up agents for ALL your projects (scan stack + create one per project):
+      /onboard ~/Projects/*
+  Or create a single project-specialist agent:
       /new-agent
 
 ==========================================================================
@@ -93,7 +95,9 @@ EOF
       $AGENTS_DIR/_assembler/target/release/assemble --validate
       ./install.sh --list   # show installed primitives
 
-  To create a new project-specialist agent:
+  To set up agents for ALL your projects (scan stack + create one per project):
+      /onboard ~/Projects/*
+  Or create a single project-specialist agent:
       /new-agent
 
 ==========================================================================
diff --git a/settings-snippet.json b/settings-snippet.json
index dd2b838..16d55ab 100644
--- a/settings-snippet.json
+++ b/settings-snippet.json
@@ -279,6 +279,18 @@
           }
         ]
       }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/first-run-onboard.sh",
+            "statusMessage": "KeiSeiKit first-run onboard nudge..."
+          }
+        ]
+      }
     ]
   }
 }