From 582b51155f1d269364ffb99f6227ac8b8f5012ab Mon Sep 17 00:00:00 2001
From: KeiSei84 <2206745@gmail.com>
Date: Fri, 22 May 2026 19:05:00 +0800
Subject: [PATCH] feat(install): first-run nudge to /onboard projects after
 bundle install
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

After install the user got no guidance to set up project agents — the summary
only mentioned /new-agent (single), never /onboard (scan all projects → create
a specialist per project). The installer is bash and can't launch a skill, so:

- New SessionStart hook first-run-onboard.sh: on the FIRST Claude Code session
  after install, injects context nudging the user/Claude to run
  `/onboard ~/Projects/*` (scan stack + create per-project agent, delegates to
  /new-agent). Fires once (marker ~/.claude/.kei-firstrun-shown), then silent.
  Reset: rm the marker.
- settings-snippet.json: wire the hook under SessionStart (matcher "*").
- lib-summary.sh next-steps: lead with `/onboard ~/Projects/*`, then /new-agent.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 hooks/first-run-onboard.sh | 31 +++++++++++++++++++++++++++++++
 install/lib-summary.sh     |  8 ++++++--
 settings-snippet.json      | 12 ++++++++++++
 3 files changed, 49 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-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..."
+          }
+        ]
+      }
     ]
   }
 }