fix: Swap Canonical CLI Name to run-kit

[sahil-noon]

Meta

Change ID	Type	Confidence	Plan	Review
gidk	fix	3.9/5.0	18/18 tasks, 24/24 acceptance ✓	✓ 2 cycles

Impact	+/−	Net
raw	+857 / −282	+575
true	+304 / −250	+54
└ impl	+254 / −214	+40
└ tests	+50 / −36	+14

_{excludes fab/, docs/ · generated by fab-kit v2.15.3}

Pipeline: intake ✓ → apply ✓ → review ✓ → hydrate ✓ → ship → review-pr

Summary

The tool has two identities: the discovery layer (GitHub repo, shll.ai page, README title) says run-kit, while the command layer (Cobra Use, version string, help-dump tool: field, Homebrew formula, docs install voice) says rk. This swaps the canonical CLI identity to run-kit, with rk remaining a permanent, fully-interchangeable alias so no existing command, script, or hook breaks.

Changes

• Cobra root identity — app/backend/cmd/rk/root.go
• help-dump frozen JSON contract — app/backend/cmd/rk/help_dump.go
• Shell completion binds BOTH names — app/backend/cmd/rk/shell_init.go
• Formula template flips real-vs-alias — .github/formula-template.rb
• Release workflow pushes the new formula file — .github/workflows/release.yml
• rk update / upgrade.go moves to the new formula identity — app/backend/cmd/rk/upgrade.go
• agent-setup hook path resolution — app/backend/cmd/rk/agent_setup.go
• User-facing message-string sweep — app/backend/cmd/rk/
• Docs voice — README.md, docs/site/install.md

Sequencing note

This PR's release plumbing now writes Formula/run-kit.rb (formerly Formula/rk.rb). Before or with the next release, sahil87/homebrew-tap needs formula_renames.json mapping "rk": "run-kit" and the old Formula/rk.rb removed, so existing rk installs upgrade seamlessly via brew's rename redirect. Tracked as out-of-scope in this change's intake (§ Out of Scope / § What Changes item 5).

[Copilot]

Pull request overview

Swaps the canonical CLI identity from rk to run-kit across the Go CLI, Homebrew distribution plumbing, and user-facing docs—while keeping rk as a permanent, fully interchangeable alias to avoid breaking existing workflows.

Changes:

• Updated Cobra root command identity/version output and help-dump JSON tool field to run-kit, with corresponding test updates.
• Ensured shell-init completion registers both run-kit and rk (zsh + bash), and updated user-facing CLI messages to prefer run-kit.
• Flipped Homebrew formula identity (install-time rename rk → run-kit plus rk symlink back) and updated release workflow to publish Formula/run-kit.rb; re-voiced README + install docs accordingly.

Reviewed changes

Copilot reviewed 31 out of 31 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
README.md	Re-voiced docs to present run-kit as canonical CLI name and updated examples/wording.
docs/site/install.md	Re-voiced install/upgrade docs to present run-kit as canonical CLI name.
.github/formula-template.rb	Flipped formula to install run-kit as the real binary and symlink rk back; updated test block expectations.
.github/workflows/release.yml	Updated release workflow to render/commit Formula/run-kit.rb with run-kit ${version} commit message.
app/backend/cmd/rk/root.go	Set Cobra root Use/Short to run-kit (canonical CLI identity).
app/backend/cmd/rk/root_test.go	Updated version output assertions to run-kit version dev.
app/backend/cmd/rk/help_dump.go	Updated help-dump JSON Tool field to run-kit.
app/backend/cmd/rk/help_dump_test.go	Updated help-dump assertions for tool/root.name/root.path = run-kit.
app/backend/cmd/rk/shell_init.go	Updated shell-init banner/errors + appended alias completion bindings for rk (zsh + bash).
app/backend/cmd/rk/shell_init_test.go	Updated tests to assert dual-name completion bindings and new banner/error text.
app/backend/cmd/rk/upgrade.go	Migrated Homebrew detection + upgrade paths to run-kit formula identity and updated messaging.
app/backend/cmd/rk/upgrade_test.go	Updated Homebrew path/arg assertions to run-kit identity.
app/backend/cmd/rk/agent_setup.go	Preferred resolving run-kit path first (fallback rk) for hook installation; updated messages.
app/backend/cmd/rk/agent_hook.go	Updated user-facing docs/comments to run-kit phrasing where appropriate.
app/backend/cmd/rk/serve.go	Updated help text/examples to show run-kit command name and point to run-kit daemon start.
app/backend/cmd/rk/daemon.go	Updated daemon command help text to run-kit phrasing.
app/backend/cmd/rk/daemon_start.go	Updated daemon-start help/output strings to run-kit phrasing.
app/backend/cmd/rk/daemon_stop.go	Updated daemon-stop help/output strings to run-kit phrasing.
app/backend/cmd/rk/daemon_restart.go	Updated daemon-restart help/output strings to run-kit phrasing.
app/backend/cmd/rk/daemon_status.go	Updated daemon-status help/output strings to run-kit phrasing.
app/backend/cmd/rk/context.go	Updated context output to reference run-kit commands and headings.
app/backend/cmd/rk/context_test.go	Updated assertions for the CLI command listing to run-kit ....
app/backend/cmd/rk/layout.go	Updated error prefix to run-kit riff.
app/backend/cmd/rk/riff.go	Updated help/error/rollback strings to run-kit phrasing.
app/backend/cmd/rk/reaper.go	Updated user-facing help text to run-kit phrasing.
fab/changes/260709-gidk-swap-canonical-cli-name-run-kit/intake.md	Captured requirements/invariants for the canonical-name swap.
fab/changes/260709-gidk-swap-canonical-cli-name-run-kit/plan.md	Detailed plan/acceptance criteria for the canonical-name swap.
fab/changes/260709-gidk-swap-canonical-cli-name-run-kit/.status.yaml	Recorded change status/metrics for the pipeline.
fab/changes/260709-gidk-swap-canonical-cli-name-run-kit/.history.jsonl	Recorded stage history/events for the pipeline run.
docs/memory/run-kit/architecture.md	Updated architecture memory to reflect run-kit canonical identity + brew details.
docs/memory/run-kit/agent-state.md	Updated agent-state memory to reflect run-kit-first path resolution + canonical identity.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[sahil-noon]

Fixed — renamed the heading to "run-kit serve — the HTTP server" and clarified it starts the server in the foreground. (a23f54e)

[sahil-noon]

Fixed — removed the serve -d/--restart/--stop examples and replaced them with the run-kit daemon start|restart|stop|status subcommands. (a23f54e)

[sahil-noon]

Fixed — quick start now uses run-kit daemon start to launch the background dashboard daemon. (a23f54e)

[sahil-noon]

Fixed — install guide now uses run-kit daemon start to launch the background dashboard daemon. (a23f54e)

[sahil-noon]

Release coordination

• This ships in v3.0.0 (just release major after merge).
• Tap follow-up (sahil87/homebrew-tap), to land only AFTER the v3 release CI publishes Formula/run-kit.rb: add formula_renames.json mapping "rk": "run-kit" and delete Formula/rk.rb. No in-binary migration code — brew's rename redirect carries old installs.
• Pre-release verification for that follow-up: with v2.5.x installed from the tap, apply the tap change locally (tap clone under $(brew --repository)/Library/Taps/sahil87/homebrew-tap) and run rk update for real — confirming the OLD binary's brew info --json=v2 sahil87/tap/rk call resolves through the rename in a form its version-comparison parser accepts. That is the one seam where old-binary behavior meets the renamed tap.