From d34a375da708b53ae5af296af6c67f95ebc75811 Mon Sep 17 00:00:00 2001
From: KeiSei84 <2206745@gmail.com>
Date: Fri, 22 May 2026 21:27:01 +0800
Subject: [PATCH] feat(install): first-run is a full guided onboarding (agents
 + sleep + cortex)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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 | 40 ++++++++++++++++++++++++--------------
 1 file changed, 25 insertions(+), 15 deletions(-)

diff --git a/hooks/first-run-onboard.sh b/hooks/first-run-onboard.sh
index 9e175ac..c2bac35 100755
--- a/hooks/first-run-onboard.sh
+++ b/hooks/first-run-onboard.sh
@@ -1,30 +1,40 @@
 #!/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).
+# 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
-# 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
+[ -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] The agent substrate is installed. Proactively offer the
-user a one-step project setup before anything else:
+[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:
 
-  • 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.
+  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"