feat(install): first-run /onboard nudge + normalize null hook matchers (#38)

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

@@ -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

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

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
 
 ==========================================================================

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..."
+          }
+        ]
+      }
     ]
   }
 }