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