fix(cli): make startup logo static by default, animate via BOMLY_LOGO opt-in (#371)

User feedback: help must render instantly. The ~2s startup animation now
only plays when BOMLY_LOGO is set (truthy value = random variant, variant
name pins one), and runs faster when it does (28 frames x 45ms ~= 1.3s,
down from 70ms ~= 2s). NO_COLOR / BOMLY_NO_ANIMATION / CI / BOMLY_QUIET
keep their meaning and still win over the opt-in.

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: bomly-guy

dev-docs/ARCHITECTURE.md

@@ -542,12 +542,14 @@ The detect stage resolves subprojects concurrently (`resolveAll` fans out to per
 - Each detector's public `ResolveGraph` rebinds `d.Logger = req.DetectorLogger(d.Logger)` on its value-receiver copy, so every private helper inherits the scoped logger with no signature churn and no shared mutable state.
 - The console encoder enables `NameKey`/`EncodeName` so the subproject scope renders as a prefix. Logs remain real-time (not buffered per subproject) because `-vv` is used precisely to watch slow or hung detectors.
 
-### Decision: startup banner frames are procedural; gating is env-var-only
+### Decision: startup banner frames are procedural; animation is opt-in; gating is env-var-only
 
-The help-path startup banner (`internal/cli/render/logo.go`) is a frame-based animation in the style of GitHub Copilot CLI's banner: the art itself changes per frame. Four variants exist — `reveal` (a boundary sweeps left to right with a scramble band), `rain` (matrix-style green code glyphs fall down the logo silhouette), `glitch` (the full logo is visible from frame one but corrupted, and the noise density decays to zero), and `slide` (rows enter alternately from the left and right edges). A random variant plays each run; `BOMLY_LOGO=<name>` pins one. All variants share the finale (finished art, tagline fading in), the frame budget (28 frames × 70ms ≈ 2s), and the cell/run-grouping renderer. Three choices worth recording:
+The help-path startup banner (`internal/cli/render/logo.go`) is a frame-based animation in the style of GitHub Copilot CLI's banner: the art itself changes per frame. Four variants exist — `reveal` (a boundary sweeps left to right with a scramble band), `rain` (matrix-style green code glyphs fall down the logo silhouette), `glitch` (the full logo is visible from frame one but corrupted, and the noise density decays to zero), and `slide` (rows enter alternately from the left and right edges). All variants share the finale (finished art, tagline fading in), the frame budget (28 frames × 45ms ≈ 1.3s), and the cell/run-grouping renderer.
+
+**The animation is opt-in; the default is the static colored logo.** The banner originally animated by default, but user feedback was consistent that a CLI — and the help command especially — must render instantly, so the default flipped to static. `BOMLY_LOGO` is the single opt-in knob: any truthy value animates a random variant, and a variant name (`reveal`, `rain`, `glitch`, `slide`) animates that variant. Three further choices worth recording:
 
 - **Frames are generated procedurally, not stored as files.** Copilot ships ~20 hand-drawn frame files plus a position→color-role→theme mapping layer. At our scale (6×42 cells, a handful of visual roles) that indirection is over-engineering: frames are computed from the final art with a deterministic FNV-1a hash (stable across runs, so tests assert exact frame properties per variant), and styling uses lightweight run-grouped style constants — consecutive same-style cells share one escape sequence. Only variant *selection* is random; frame content is deterministic.
-- **Gating is env-var-only (`NO_COLOR`, `BOMLY_NO_ANIMATION`, `CI`, `BOMLY_QUIET`), deliberately not a config key.** Cobra's `execute()` returns `flag.ErrHelp` right after flag parsing, *before* the `PersistentPreRunE` chain where `options.ResolveConfig` runs — so on `bomly --help` / `bomly <cmd> --help` (the banner's primary path) resolved config simply does not exist yet. A `logo.animate` config key would silently work only for bare `bomly` and `bomly help <cmd>`, which is a trap. When animation is gated off but stderr is a TTY, the static final frame prints instead (plain under `NO_COLOR`, colored otherwise); non-TTY stderr prints nothing.
+- **Gating is env-var-only (`BOMLY_LOGO` to opt in; `NO_COLOR`, `BOMLY_NO_ANIMATION`, `CI`, `BOMLY_QUIET` to force static), deliberately not a config key.** Cobra's `execute()` returns `flag.ErrHelp` right after flag parsing, *before* the `PersistentPreRunE` chain where `options.ResolveConfig` runs — so on `bomly --help` / `bomly <cmd> --help` (the banner's primary path) resolved config simply does not exist yet. A `logo.animate` config key would silently work only for bare `bomly` and `bomly help <cmd>`, which is a trap. When animation is gated off but stderr is a TTY, the static final frame prints instead (plain under `NO_COLOR`, colored otherwise); non-TTY stderr prints nothing.
 - **The animation leaves cursor visibility unchanged.** Hiding the cursor would make the animation slightly cleaner, but a process-level interrupt can bypass deferred cleanup and leave the user's shell cursor hidden. Avoiding that terminal-state mutation keeps interruption safe without introducing signal handling into the render package.
 
 ## Build Modes

docs/TROUBLESHOOTING.md

@@ -129,21 +129,21 @@ ANSI escapes are auto-stripped when stdout is not a TTY, but some CI runners rep
 NO_COLOR=1 bomly scan
 ```
 
-## Controlling the startup animation
+## Controlling the startup logo
 
-`bomly --help` plays a short (~2s) logo animation when stderr is an interactive terminal. A random variant plays each run; pin a favorite with `BOMLY_LOGO` (`reveal`, `rain`, `glitch`, or `slide`):
+`bomly --help` prints a static logo when stderr is an interactive terminal. To play a short (~1.3s) logo animation instead, set `BOMLY_LOGO` to a truthy value — a random variant plays each run:
 
 ```bash
-BOMLY_LOGO=rain bomly --help
+BOMLY_LOGO=1 bomly --help
 ```
 
-To skip the animation and print a static logo instead:
+Pin a favorite variant by name (`reveal`, `rain`, `glitch`, or `slide`):
 
 ```bash
-BOMLY_NO_ANIMATION=1 bomly --help
+BOMLY_LOGO=rain bomly --help
 ```
 
-The animation is also skipped automatically when `CI` or `BOMLY_QUIET` is set, and `NO_COLOR` switches to a plain uncolored logo. When stderr is not a terminal (pipes, redirects), no logo is printed at all.
+The animation is skipped even when `BOMLY_LOGO` is set if `BOMLY_NO_ANIMATION`, `CI`, or `BOMLY_QUIET` is set, and `NO_COLOR` switches to a plain uncolored logo. When stderr is not a terminal (pipes, redirects), no logo is printed at all.
 
 ## Need more detail
 

internal/cli/render/logo.go

@@ -12,9 +12,9 @@ import (
 )
 
 const (
-	startupLogoFrameDelay = 70 * time.Millisecond
+	startupLogoFrameDelay = 45 * time.Millisecond
 
-	// logoFrameCount is the total animation length (~2s at 70ms per frame);
+	// logoFrameCount is the total animation length (~1.3s at 45ms per frame);
 	// the last two frames hold the finished art while the tagline fades in.
 	logoFrameCount       = 28
 	logoRevealFrameCount = logoFrameCount - 2
@@ -35,11 +35,13 @@ const (
 	logoStaticPlain
 )
 
-// StartupLogo plays a brief Bomly logo animation when w is an attached TTY.
-// On non-TTY writers (pipes, files), it is a silent no-op. The animation is
-// skipped in favor of a static logo when NO_COLOR (plain), BOMLY_NO_ANIMATION,
-// CI, or BOMLY_QUIET (colored) are set. A random animation variant plays each
-// run; BOMLY_LOGO pins one by name (reveal, rain, glitch, slide).
+// StartupLogo prints the Bomly logo when w is an attached TTY. On non-TTY
+// writers (pipes, files), it is a silent no-op. By default the logo is a
+// static colored banner so help stays instant; setting BOMLY_LOGO to a truthy
+// value opts into a brief animation with a random variant, and setting it to a
+// variant name (reveal, rain, glitch, slide) pins that variant. NO_COLOR
+// forces a plain static logo, and BOMLY_NO_ANIMATION, CI, or BOMLY_QUIET force
+// a static colored logo even when BOMLY_LOGO is set.
 func StartupLogo(w io.Writer) {
 	file, ok := w.(*os.File)
 	if !ok || file == nil {
@@ -80,15 +82,19 @@ func StartupLogo(w io.Writer) {
 
 // startupLogoMode applies the environment gates. NO_COLOR follows the
 // no-color.org convention (any non-empty value); the remaining variables are
-// treated as boolean flags via envFlagSet.
+// treated as boolean flags via envFlagSet. Animation is opt-in via BOMLY_LOGO;
+// the off-switches (BOMLY_NO_ANIMATION, CI, BOMLY_QUIET) win over it.
 func startupLogoMode() logoMode {
 	if os.Getenv("NO_COLOR") != "" {
 		return logoStaticPlain
 	}
 	if envFlagSet("BOMLY_NO_ANIMATION") || envFlagSet("CI") || envFlagSet("BOMLY_QUIET") {
 		return logoStaticColor
 	}
-	return logoAnimate
+	if envFlagSet("BOMLY_LOGO") {
+		return logoAnimate
+	}
+	return logoStaticColor
 }
 
 // envFlagSet reports whether the named environment variable is set to a truthy

internal/cli/render/logo_test.go

@@ -7,10 +7,10 @@ import (
 )
 
 // clearLogoEnv isolates logo gating tests from the ambient environment (CI
-// runners set CI=true, which would flip animate-expected cases).
+// runners set CI=true, and a developer's BOMLY_LOGO would flip the default).
 func clearLogoEnv(t *testing.T) {
 	t.Helper()
-	for _, name := range []string{"NO_COLOR", "BOMLY_NO_ANIMATION", "CI", "BOMLY_QUIET"} {
+	for _, name := range []string{"NO_COLOR", "BOMLY_NO_ANIMATION", "CI", "BOMLY_QUIET", "BOMLY_LOGO"} {
 		t.Setenv(name, "")
 	}
 }
@@ -148,14 +148,19 @@ func TestStartupLogoMode(t *testing.T) {
 		env  map[string]string
 		want logoMode
 	}{
-		{name: "default animates", env: nil, want: logoAnimate},
+		{name: "default colored static", env: nil, want: logoStaticColor},
+		{name: "logo flag animates", env: map[string]string{"BOMLY_LOGO": "1"}, want: logoAnimate},
+		{name: "logo variant animates", env: map[string]string{"BOMLY_LOGO": "rain"}, want: logoAnimate},
+		{name: "logo flag zero stays static", env: map[string]string{"BOMLY_LOGO": "0"}, want: logoStaticColor},
+		{name: "logo flag false stays static", env: map[string]string{"BOMLY_LOGO": "FALSE"}, want: logoStaticColor},
 		{name: "NO_COLOR plain static", env: map[string]string{"NO_COLOR": "1"}, want: logoStaticPlain},
 		{name: "NO_COLOR wins over no-animation", env: map[string]string{"NO_COLOR": "1", "BOMLY_NO_ANIMATION": "1"}, want: logoStaticPlain},
+		{name: "NO_COLOR wins over logo flag", env: map[string]string{"NO_COLOR": "1", "BOMLY_LOGO": "1"}, want: logoStaticPlain},
 		{name: "no-animation colored static", env: map[string]string{"BOMLY_NO_ANIMATION": "1"}, want: logoStaticColor},
-		{name: "no-animation zero animates", env: map[string]string{"BOMLY_NO_ANIMATION": "0"}, want: logoAnimate},
-		{name: "no-animation false animates", env: map[string]string{"BOMLY_NO_ANIMATION": "FALSE"}, want: logoAnimate},
+		{name: "no-animation wins over logo flag", env: map[string]string{"BOMLY_NO_ANIMATION": "1", "BOMLY_LOGO": "rain"}, want: logoStaticColor},
+		{name: "no-animation zero stays static", env: map[string]string{"BOMLY_NO_ANIMATION": "0"}, want: logoStaticColor},
 		{name: "CI colored static", env: map[string]string{"CI": "true"}, want: logoStaticColor},
-		{name: "CI zero animates", env: map[string]string{"CI": "0"}, want: logoAnimate},
+		{name: "CI wins over logo flag", env: map[string]string{"CI": "true", "BOMLY_LOGO": "1"}, want: logoStaticColor},
 		{name: "quiet colored static", env: map[string]string{"BOMLY_QUIET": "1"}, want: logoStaticColor},
 	}
 	for _, tc := range cases {