Toolkit Update

Toolkit update

The toolkit ships in two layers, and they update through different mechanisms. Getting this wrong is the most common source of confusion, so establish which layer the user means before doing anything.

1. Establish the current state

~/.claude/bin/fkt status

This is offline and instant. It prints the installed version, the channel, the cached check result, whether the worktree is clean, and any security advisories that apply to the installed version.

2. Check for an update

~/.claude/bin/fkt check

Exit codes matter here — read them, do not parse the prose:

Results are cached for 12 hours. Pass --force only when the user explicitly wants a fresh network check; otherwise the cache is the right answer.

3. Apply it

~/.claude/bin/fkt update

Fast-forward only. It refuses (exit 20) rather than destroying work when:

• tracked files are modified — report git -C ~/.claude status to the user and stop; do not stash or discard on their behalf;
• the checkout carries local commits that are not on the target — show git -C ~/.claude log --oneline <target>..HEAD and stop.

In both cases the fix is the user's decision. Never pass --force to git, never reset --hard, never clean.

Add -y only when the user has already said to go ahead. --dry-run shows the commits an update would bring in without touching anything.

After a successful update the toolkit runs any pending migrations, then asks for a Claude Code restart. Tell the user that, and mention that the plugin half updates separately:

/plugin marketplace update fk-toolkit

4. Channels

~/.claude/bin/fkt channel          # show
~/.claude/bin/fkt channel stable   # latest v* release tag (default)
~/.claude/bin/fkt channel edge     # origin/main

stable only moves to validated, tagged releases. edge tracks the development branch and will occasionally be broken. Switching clears the update cache.

5. Turning it down or off

~/.claude/bin/fkt snooze 168   # hide this update for a week
~/.claude/bin/fkt disable      # stop update checks entirely
~/.claude/bin/fkt enable       # turn them back on

A newer release always breaks through a snooze. disable stops update checks but not security advisories — that is deliberate. Turn those off separately, and only if the user asks:

~/.claude/bin/fkt config security_notices false

What this skill must never do

• Run fkt update -y without the user having agreed to the update.
• Work around a refusal (exit 20). The refusal is the feature.
• Edit the user's settings.json, config.json, or any *.local.md.
• Reinstall via install.sh to "fix" a failed update — that is a much heavier operation with different side effects. Report the failure instead.