feat(install): first-run is a full guided onboarding (agents + sleep + cortex)

Sleep/cortex setup were left as separate things the user had to discover. Make
the SessionStart first-run hook a single ordered post-install checklist that
Claude walks the user through: (1) /onboard projects → per-project agents,
(2) /sleep-setup → nightly REM (recommend local-only, no remote git needed),
(3) /cortex-setup (only if the cortex daemon primitive is installed). Confirm +
run each, skippable. Fires once (marker), then silent.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

hooks/first-run-onboard.sh

@@ -0,0 +1,41 @@
+#!/bin/sh
+# first-run-onboard — on the FIRST Claude Code session after a KeiSeiKit install,
+# inject a one-time POST-INSTALL ONBOARDING checklist so Claude walks the user
+# through ALL setup in order (agents → sleep → cortex), instead of leaving each
+# as a separate thing the user has to discover. Event: SessionStart (stdout is
+# injected into session context). Fires ONCE (marker), then silent forever.
+# Reset / re-run: rm ~/.claude/.kei-firstrun-shown
+
+MARKER="$HOME/.claude/.kei-firstrun-shown"
+[ -f "$MARKER" ] && exit 0
+[ -d "$HOME/.claude/agents" ] || exit 0
+
+PROJ="$HOME/Projects"
+[ -d "$PROJ" ] || PROJ="$HOME/projects"
+[ -d "$PROJ" ] || PROJ="$HOME/Projects"
+
+# Cortex step only if the cortex daemon primitive landed (cortex / full* profiles).
+CORTEX_STEP=""
+if [ -d "$HOME/.claude/agents/_primitives/_rust/kei-cortex" ] \
+   || [ -x "$HOME/.claude/agents/_primitives/_rust/target/release/kei-cortex" ]; then
+  CORTEX_STEP="  3. /cortex-setup          — cortex daemon + UI (token, whisper, model, bundle)
+"
+fi
+
+cat <<EOF
+[KeiSeiKit · FIRST-RUN ONBOARDING] The substrate is installed. Before other
+work, proactively walk the user through this one-time setup, step by step, in
+order — confirm each step with the user, then run it:
+
+  1. /onboard $PROJ/*   — scan every project, detect stack, create a
+     project-specialist agent per project (delegates to /new-agent).
+  2. /sleep-setup           — nightly memory (REM) consolidation. Recommend
+     local-only mode (runs on this Mac, no remote/cloud git needed) unless the
+     user wants the cloud agent (needs a cloud-reachable private git repo).
+$CORTEX_STEP
+Start with step 1. Offer to do them one after another as a guided flow; the user
+can skip any. Do NOT make the user discover these on their own.
+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..."
+          }
+        ]
+      }
     ]
   }
 }