feat(onboarding): /update command + SessionStart drift hook

[abdout]

Why

After the 3 onboarding-overhaul PRs landed (#111, #113, #114), the question became: how does a teammate who paste-installed last week pick up today's changes? Three different layers, each with a different cadence:

Layer	Source	Cadence	Previous path
Engine config (~/.claude/*)	databayt/kun	every kun PR	manual: git pull ~/kun → setup.sh
Org product repos	each repo's main	daily	sync-repos.sh all
Tools (Node, gh, pnpm, vercel, IDEs, Chrome)	brew/apt/winget/npm	weekly	re-run bootstrap
Claude Code CLI	claude.ai/install.sh	daily	(auto-updates)

Audit on 2026-05-25 found:

1. Three scripts to remember, teammates forget the order
2. sync.sh / sync.ps1 was broken — pulled from databayt/codebase (engine moved to databayt/kun long ago) with a hardcoded stale list of 30 agents (real count differs)
3. No drift visibility — teammates discover staleness only when something breaks
4. No "Staying current" docs section

After this PR, the answer to "how do I update?" is c /update.

What lands

.claude/commands/update.md — the slash command

Chains: git pull ~/kun → setup.sh → sync-repos.sh all → health.sh. Flags: --tools (also re-runs the smart-install bootstrap from #113); --dry (print only). Prints a one-line summary at the end (engine: <old> → <new>; repos: X synced; tools: skipped|refreshed; health: <status>).

.claude/hooks/session-start-kun-drift.{sh,ps1} — drift hook

Silently git fetches ~/kun at every Claude Code session start. If behind, prints ⚠️ ~/kun is N commits behind — run \c /update` to refresh. **Never auto-pulls** — respects the explicit anti-auto-update posture from mcp.mdx`. Silent on offline machines + when up to date.

Registered in .claude/settings.json (mac/linux) and .claude/settings-windows.json under the SessionStart hook chain. Both hook script and registration ride along with setup.sh.

setup.sh + setup.ps1 — copy .claude/hooks/*

New block in both scripts copies the hook directory during install or update, alongside existing agents/commands/rules/memory/scripts copies.

Hard-deleted .claude/scripts/sync.sh + .ps1

Their replacement is setup.sh (already role-aware, already pulls from local ~/kun/.claude/* dynamically, already detects MODE=update). /update chains it.

content/docs/claude-code.mdx

• "Configuration Sync" section rewritten to point at /update
• File-tree listing updated: removed sync.sh / sync.ps1; added installer* / onboarding-* / vercel-pull / health / secrets references

content/docs/onboarding.mdx — new "Staying current" section

After "Auto-resume" (~line 519). Cheat-sheet table covering the 4 layers with source-of-truth + refresh mechanism. Documents the drift hook + the explicit non-bump for MCP versions + when to run vercel-pull.sh manually.

Test plan

• On a machine 1+ commits behind kun: c /update runs to completion; summary line accurate; ~/.claude/agents/ count matches ~/kun/.claude/agents/
• Start a new Claude Code session on a machine ≥1 commit behind: the ⚠️ ~/kun is N commit(s) behind line appears in the session header
• Start a session on an up-to-date machine: hook is silent
• c /update --tools: runs the smart-install pass; brew/apt/winget output shows "up to date" or "upgraded" per tool
• setup.sh after this PR: prints hooks (2) and ~/.claude/hooks/session-start-kun-drift.sh exists + is executable
• grep -rn 'scripts/sync\.\(sh\|ps1\)' .claude content/docs is empty
• pnpm build of docs site green

Commits

5b2cd34	rm sync.sh + sync.ps1 (got stranded on its own because git add tripped on pre-staged deletions)
44d897a	the rest: /update command + hook files + setup script updates + docs

Squash-merge will collapse these into one. Net: +220 / -131 across both commits.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
kun	Ready	Preview, Comment	May 25, 2026 6:01am