avo 4.1.2 → 4.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fb3546ef7dd6b1a139d47614126266994823ab88f00ec3e426b95b654fcc6b1a
-  data.tar.gz: 035f10d186aeaf732f6a3d68713568d839ee4b408e88d8f03c140374b816b7df
+  metadata.gz: 342b9da8cac48e785b94b6261a29cf466d2320d46a67d94a42b7779afbba3232
+  data.tar.gz: 5085b06b9ec693fea5538c8c349766d1afae278be2bf0ffa8329b5e535a70f1b
 SHA512:
-  metadata.gz: 9615e1f3b3c3971a5d522c35d309201d1fbaa35aad6c00cf2d6ddab8d2bde4a595fa5de19dd26eefbba9df69527cdecff8a28cb8884c5f1a977adf6138d10e94
-  data.tar.gz: bb7bd93dcd97b4dbf21117e3d273c7bf63afbbb10e0eab8c34ef9d4769646cdd7d8fd2dceb00530ee9b5ca0034864b59096340f5f8c1ba710c4373e045848e7e
+  metadata.gz: e735bcba96cdfa3a8c3c3eb3a1885076bcd4c4d168bcf9f529404474fac628a4fb2d4a4f225c26f6598600cd9846e046ce2e85c76fb23d5270f85186476bd3df
+  data.tar.gz: 84f62915ab3f3b456669538a582b0dec138c8057fdb60cc4fd578e649f03ffa159974079f1deee3c1a4586eff7d67dca23fa2f644d8bf4b121754b399d6f234f

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    avo (4.1.2)
+    avo (4.1.3)
       actionview (>= 6.1)
       active_link_to
       activerecord (>= 6.1)

data/lib/avo/version.rb

@@ -1,3 +1,3 @@
 module Avo
-  VERSION = "4.1.2" unless const_defined?(:VERSION)
+  VERSION = "4.1.3" unless const_defined?(:VERSION)
 end

data/lib/generators/avo/skills_generator.rb

@@ -1,3 +1,4 @@
+require "tmpdir"
 require_relative "base_generator"
 require_relative "skills_install_panel"
 
@@ -5,12 +6,12 @@ module Generators
   module Avo
     # Installs the Avo skills loader into the host app.
     #
-    # Only the loader is copied — the skills themselves stay inside the gem, which
-    # is the whole point: a copied skill tree drifts from the locked Avo version
-    # with nothing to refresh it. Re-running this generator refreshes the loader.
+    # Only the loader is written — the skills themselves stay inside the gem,
+    # which is the point: a copied skill tree drifts from the locked Avo version
+    # with nothing to refresh it.
     #
-    # Deliberately its own namespace rather than part of `avo:install`, so it does
-    # not change behavior for apps that already ran the installer.
+    # There is one way to run this and it asks. No flags: a flag per question is
+    # a second surface to document, keep in step with the screens, and get wrong.
     class SkillsGenerator < BaseGenerator
       source_root File.expand_path("templates", __dir__)
 
@@ -18,212 +19,281 @@ module Generators
       desc "Install the Avo skills loader so coding agents read the instructions that ship with this app's Avo version."
 
       # Claude Code scans .claude/skills; .agents/skills is the cross-agent
-      # convention; .cursor/skills is what Cursor reads. Installing to all three
-      # is why the loader is copied rather than symlinked — a symlink into a
-      # version-named gem directory breaks on the next `bundle update`.
-      TARGETS = {
-        "claude" => ".claude/skills/avo",
-        "agents" => ".agents/skills/avo",
-        "cursor" => ".cursor/skills/avo"
+      # convention; .cursor/skills is what Cursor reads.
+      AGENTS = {
+        "agents" => {dir: ".agents/skills/avo", label: ".agents/skills", hint: "Codex, Gemini CLI, Goose, Amp, OpenCode"},
+        "claude" => {dir: ".claude/skills/avo", label: ".claude/skills", hint: "Claude Code"},
+        "cursor" => {dir: ".cursor/skills/avo", label: ".cursor/skills", hint: "Cursor"}
       }.freeze
 
-      # Where a pre-gem install of avo-hq/skills materialized its catalog.
-      # `npx skills add` writes project-locally, so the stale copies land in the
-      # same directories this generator installs into.
-      LEGACY_ROOTS = [
-        ".claude/skills",
-        ".agents/skills",
-        ".cursor/skills"
-      ].freeze
-
-      # Checked, reported, and never deleted. This directory is shared by every
-      # project on the machine — a skill here may be deliberately installed for
-      # a different app, and a generator run inside one project has no business
-      # removing it. The user gets the command instead.
-      GLOBAL_LEGACY_ROOT = "~/.claude/skills"
+      # The copy the others link to. Vendor-neutral on purpose: the real file
+      # should not live in a directory named after one tool.
+      CANONICAL = "agents"
 
-      class_option :global, type: :boolean,
-        desc: "Install to your home directory instead of this app, so every Avo project on this machine shares one loader"
-      class_option :only, type: :string, desc: "Install one target only (#{TARGETS.keys.join(", ")})"
-      class_option :panel, type: :boolean, default: true,
-        desc: "Show the interactive install panel (skipped automatically without a TTY, or when --global/--only is given)"
-      class_option :path, type: :string, desc: "Install to this directory instead of the default scan paths"
-      class_option :clean_legacy, type: :boolean,
-        desc: "Remove skills left by a pre-gem install of avo-hq/skills (skips the prompt either way)"
+      # Where a pre-gem install of avo-hq/skills left its catalog, and where an
+      # early 4.1.1 install left the resolver we no longer ship.
+      LEGACY_ROOTS = [".claude/skills", ".agents/skills", ".cursor/skills"].freeze
+      GLOBAL_LEGACY_ROOT = "~/.claude/skills"
 
       def install_loader
-        return if panel_cancelled?
-
-        # Only the loader is written. The resolver stays inside the gem, where
-        # `bundle update` refreshes it and it cannot drift; a copy in the app
-        # would be one more file to keep in sync, and 250 lines of shell in
-        # someone's repo is a reasonable thing to be suspicious of.
-        destinations.each { |destination| copy_file "skills/SKILL.md", File.join(destination, "SKILL.md") }
-      end
+        return if answers.cancelled?
 
-      # A leftover catalog sits in the same scan directories as the loader and
-      # can shadow it, silently serving instructions written for a different Avo
-      # version — which is the whole problem this feature removes. Install time
-      # is the right place to catch it: it is the one moment we know the user is
-      # present and thinking about skills.
-      def clean_legacy_skills
-        leftovers = legacy_skill_dirs
-        global = global_legacy_skill_dirs
-        return if leftovers.empty? && global.empty?
-
-        if leftovers.any?
-          say "\nFound #{pluralize_skills(leftovers.length)} in this project from a previous avo-hq/skills install:"
-          by_directory(leftovers).each { |dir, count| say "  #{dir}#{" " * padding(dir)}#{count}", :yellow }
-          say "These are not version-pinned and can shadow the skills that ship with your Avo gem."
-
-          if remove_legacy?
-            by_directory(leftovers).each do |dir, count|
-              leftovers.select { |path| display_dir(path) == dir }.each { |path| FileUtils.rm_rf(path) }
-              say_status :remove, "#{dir} (#{pluralize_skills(count)})", :red
-            end
+        canonical = nil
+        destinations.each do |dir|
+          if canonical.nil? || !link?
+            copy_file "skills/SKILL.md", File.join(dir, "SKILL.md")
+            canonical ||= dir
           else
-            report_kept(leftovers)
+            link_or_copy(canonical, dir)
           end
         end
+      end
 
-        report_global(global) if global.any?
-        say "\nIf you installed the Claude Code plugin, remove it with: /plugin uninstall avo-skills"
+      def clean_legacy_skills
+        return if answers.cancelled?
+
+        remove_or_report(legacy_skill_dirs, remove: remove_legacy?)
+        remove_or_report(shared_legacy_skill_dirs, remove: remove_shared_legacy?)
       end
 
       no_tasks do
-        def remove_legacy?
-          return options[:clean_legacy] unless options[:clean_legacy].nil?
-          # No TTY to answer, so keep the files and say where they are.
-          return false if options[:quiet]
+        def answers
+          @answers ||= SkillsInstallPanel.interactive? ? ask_the_user : take_the_defaults
+        end
+
+        # Answering "No" on the last screen is a cancel — the user was shown what
+        # was about to happen and declined it.
+        def ask_the_user
+          result = SkillsInstallPanel.new(screens, defaults: defaults).run
+          return declined if result.cancelled? || result[:confirm] == false
 
-          yes?("\nRemove them? [y/N]")
+          SkillsInstallPanel::Result.new(defaults.merge(result.answers), false)
         end
 
-        def report_kept(leftovers)
-          say "\nLeaving them in place. Remove them later with:", :yellow
-          say "  #{removal_command(leftovers)}"
+        def declined
+          say("Cancelled. Nothing was installed.", :yellow)
+          SkillsInstallPanel::Result.new({}, true)
         end
 
-        def report_global(global)
-          say "\nAlso found #{pluralize_skills(global.length)} in #{GLOBAL_LEGACY_ROOT}, shared by every project on this machine:", :yellow
-          by_directory(global).each { |dir, count| say "  #{dir}#{" " * padding(dir)}#{count}" }
-          say "Not removing those — another project may still want them. If not, run:"
-          say "  #{removal_command(global)}"
+        # No terminal to ask on — piped, or a test run. Install what the screens
+        # recommend, but neither destructive one: nobody was there to decline.
+        def take_the_defaults
+          SkillsInstallPanel::Result.new(defaults.merge(clean_legacy: false, clean_shared_legacy: false), false)
         end
 
-        # One glob per directory rather than one path per skill: with the full
-        # catalog installed this is the difference between a readable command
-        # and 35 pasted paths.
-        def removal_command(dirs)
-          "rm -rf #{by_directory(dirs).keys.map { "#{_1}avo-*" }.join(" ")}"
+        def defaults
+          {
+            where: "app", agents: AGENTS.keys, link: symlinks_supported?,
+            clean_legacy: true, clean_shared_legacy: true, confirm: true
+          }
         end
 
-        # Directory => how many legacy skills sit in it, so a full catalog
-        # reports three lines instead of a hundred.
-        def by_directory(dirs)
-          dirs.group_by { display_dir(_1) }.transform_values(&:count).sort.to_h
+        # A cleanup screen only when there is something to remove there, and the
+        # link screen only once there is more than one directory to keep in step.
+        def screens
+          list = [where_screen]
+          list << legacy_screen if legacy_skill_dirs.any?
+          list << shared_legacy_screen if shared_legacy_skill_dirs.any?
+          list << agents_screen
+          list << link_screen if symlinks_supported?
+          list << confirm_screen
+          list
         end
 
-        def display_dir(path)
-          "#{display_path(File.dirname(path))}/"
+        def where_screen
+          SkillsInstallPanel::Screen.new(
+            key: :where, kind: :radio, title: "Where should the Avo skills loader go?",
+            hint: "It finds the gem from the working directory, so one copy serves every project correctly.",
+            options: [
+              SkillsInstallPanel::Option.new(key: "app", label: "This app", hint: "commit it, your team gets it", recommended: true),
+              SkillsInstallPanel::Option.new(key: "machine", label: "This machine", hint: "one install, every Avo project")
+            ]
+          )
         end
 
-        def padding(dir)
-          [2, 28 - dir.length].max
+        def legacy_screen
+          SkillsInstallPanel::Screen.new(
+            key: :clean_legacy, kind: :radio,
+            title: "Remove the #{pluralize_skills(legacy_skill_dirs.length)} left by an earlier install?",
+            hint: "They are not version-pinned and can shadow the skills that ship with your gem.",
+            options: [
+              SkillsInstallPanel::Option.new(key: true, label: "Yes, remove them", recommended: true),
+              SkillsInstallPanel::Option.new(key: false, label: "No, leave them")
+            ]
+          )
         end
 
-        def pluralize_skills(count)
-          "#{count} skill#{"s" unless count == 1}"
+        # Kept a separate question from the project one: this directory is shared
+        # with every other project on the machine, and that is worth its own yes.
+        def shared_legacy_screen
+          SkillsInstallPanel::Screen.new(
+            key: :clean_shared_legacy, kind: :radio,
+            title: "Remove the #{pluralize_skills(shared_legacy_skill_dirs.length)} in #{GLOBAL_LEGACY_ROOT}?",
+            hint: "That directory is shared by every project on this machine, not just this one.",
+            options: [
+              SkillsInstallPanel::Option.new(key: true, label: "Yes, remove them", recommended: true),
+              SkillsInstallPanel::Option.new(key: false, label: "No, leave them")
+            ]
+          )
         end
 
-        # Cleanup is scoped to wherever this run installs. A project install must
-        # not delete from the home directory another project may still rely on;
-        # a --global install is exactly the case where home is fair game.
-        def legacy_skill_dirs
-          roots = global_install? ? [File.expand_path(GLOBAL_LEGACY_ROOT)] : LEGACY_ROOTS.map { File.expand_path(_1, destination_root) }
-          skill_dirs_in(roots)
+        def confirm_screen
+          SkillsInstallPanel::Screen.new(
+            key: :confirm, kind: :radio, title: "Run the installation?", hint: nil,
+            summary: ->(a) { summary_lines(a) },
+            options: [
+              SkillsInstallPanel::Option.new(key: true, label: "Yes, install", recommended: true),
+              SkillsInstallPanel::Option.new(key: false, label: "No, cancel")
+            ]
+          )
         end
 
-        def global_legacy_skill_dirs
-          return [] if global_install?
+        def summary_lines(a)
+          agents = Array(a[:agents]).select { AGENTS.key?(_1) }
+          root = (a[:where] == "machine") ? "~/" : ""
+          lines = [
+            summary_row("Install to", (a[:where] == "machine") ? "this machine (your home directory)" : "this app"),
+            summary_row("Directories", agents.map { "#{root}#{AGENTS.fetch(_1)[:label]}" }.join(", "))
+          ]
+          lines << summary_row("Extra copies", a[:link] ? "symlinked to #{root}#{AGENTS.fetch(CANONICAL)[:label]}" : "written separately") if agents.length > 1
+          lines << summary_row("Remove", "#{pluralize_skills(legacy_skill_dirs.length)} left in this project") if legacy_skill_dirs.any? && a[:clean_legacy]
+          lines << summary_row("Remove", "#{pluralize_skills(shared_legacy_skill_dirs.length)} in #{GLOBAL_LEGACY_ROOT}") if shared_legacy_skill_dirs.any? && a[:clean_shared_legacy]
+          lines
+        end
 
-          skill_dirs_in([File.expand_path(GLOBAL_LEGACY_ROOT)])
+        def summary_row(label, value) = "#{label.ljust(14)}#{value}"
+
+        def agents_screen
+          SkillsInstallPanel::Screen.new(
+            key: :agents, kind: :checkbox, title: "Which agents should read it?", hint: nil,
+            options: AGENTS.map { |key, a| SkillsInstallPanel::Option.new(key: key, label: a[:label], hint: a[:hint]) }
+          )
         end
 
-        # Only directories that actually look like a skill are eligible — a
-        # `rm -rf` driven by a name glob alone is not something to hand a user.
-        def skill_dirs_in(roots)
-          roots.flat_map { |root| Dir.glob(File.join(root, "avo-*")) }
-            .select { |dir| File.directory?(dir) && File.file?(File.join(dir, "SKILL.md")) }
-            .uniq
-            .sort
+        def link_screen
+          SkillsInstallPanel::Screen.new(
+            key: :link, kind: :radio, title: "How should the extra directories be written?",
+            hint: "One real file keeps them identical and makes an update a single edit.",
+            options: [
+              SkillsInstallPanel::Option.new(key: true, label: "Symlink to one copy", hint: ".#{CANONICAL}/skills holds the file", recommended: true),
+              SkillsInstallPanel::Option.new(key: false, label: "Separate copies", hint: "use when symlinks are awkward")
+            ],
+            visible_when: ->(a) { Array(a[:agents]).length > 1 }
+          )
         end
 
-        def display_path(dir)
-          home = File.expand_path("~")
-          return dir.sub(home, "~") if dir.start_with?(home) && !dir.start_with?(File.expand_path(destination_root))
+        def destinations
+          dirs = selected_agent_keys.map { |k| AGENTS.fetch(k)[:dir] }
+          global? ? dirs.map { File.expand_path("~/#{_1}") } : dirs
+        end
 
-          dir.delete_prefix("#{File.expand_path(destination_root)}/")
+        # Canonical first, so it is the one written as a real file.
+        def selected_agent_keys
+          keys = Array(answers[:agents]).select { AGENTS.key?(_1) }
+          keys = AGENTS.keys if keys.empty?
+          keys.sort_by { |k| (k == CANONICAL) ? 0 : 1 }
         end
 
-        # The loader holds no per-project state — it finds the app by walking up
-        # from the working directory at run time — so one global copy serves
-        # every Avo project on the machine, each resolving its own lock.
-        def destinations
-          return [options[:path]] if options[:path].present?
+        def global? = answers[:where] == "machine"
+
+        def link? = !!answers[:link]
 
-          return roots.map { |target| File.expand_path("~/#{target}") } if global_install?
+        def remove_legacy? = !!answers[:clean_legacy]
 
-          if (only = options[:only]).present?
-            target = TARGETS[only]
-            raise ::Thor::Error, "Unknown --only value #{only.inspect}. Valid values: #{TARGETS.keys.join(", ")}." if target.nil?
+        def remove_shared_legacy? = !!answers[:clean_shared_legacy]
 
-            return [target]
+        def remove_or_report(dirs, remove:)
+          return if dirs.empty?
+
+          if remove
+            by_directory(dirs).each do |dir, count|
+              dirs.select { |p| display_dir(p) == dir }.each { |p| FileUtils.rm_rf(p) }
+              say_status :remove, "#{dir} (#{pluralize_skills(count)})", :red
+            end
+          else
+            # By directory, never one line per skill: the full catalog is 35 per
+            # scan path, and listing them buries everything else.
+            say "\nLeaving #{pluralize_skills(dirs.length)} in place:", :yellow
+            by_directory(dirs).each { |dir, count| say "  #{dir}  #{count}" }
+            say "Remove them later with:"
+            say "  #{removal_command(dirs)}"
           end
+        end
 
-          TARGETS.values
+        # Probed, not assumed: Windows without developer mode, and some CI
+        # checkouts, cannot create one. A real file beats a broken install.
+        def symlinks_supported?
+          return @symlinks_supported if defined?(@symlinks_supported)
+
+          @symlinks_supported =
+            begin
+              Dir.mktmpdir do |dir|
+                File.write(File.join(dir, "target"), "x")
+                File.symlink(File.join(dir, "target"), File.join(dir, "link"))
+                File.symlink?(File.join(dir, "link"))
+              end
+            rescue NotImplementedError, SystemCallError
+              false
+            end
         end
 
-        def roots
-          return [TARGETS.fetch(options[:only])] if options[:only].present? && TARGETS.key?(options[:only])
-          return panel_choice.targets.map { |key| TARGETS.fetch(key) } if panel_choice
+        # `destination` is absolute for a machine-wide install and relative for
+        # an app one, so expand rather than join — File.join would nest the
+        # absolute path under the app root.
+        def link_or_copy(canonical, destination)
+          target = File.expand_path(File.join(destination, "SKILL.md"), destination_root)
+          source = File.expand_path(File.join(canonical, "SKILL.md"), destination_root)
+          FileUtils.mkdir_p(File.dirname(target))
+          FileUtils.rm_f(target)
+          File.symlink(relative_link(source, target), target)
+          say_status :symlink, "#{display_path(destination)}/SKILL.md → #{display_path(canonical)}/SKILL.md", :green
+        rescue NotImplementedError, SystemCallError => e
+          say_status :copy, "#{display_path(destination)}/SKILL.md (symlink unavailable: #{e.class})", :yellow
+          copy_file "skills/SKILL.md", File.join(destination, "SKILL.md")
+        end
 
-          TARGETS.values
+        # Relative so the link survives the repo being cloned elsewhere.
+        def relative_link(source, target)
+          Pathname.new(source).relative_path_from(Pathname.new(File.dirname(target))).to_s
         end
 
-        # Shown once, memoized, and only when the user has not already answered
-        # with flags. Without a TTY there is nobody to answer, so the defaults
-        # stand and the install is silent.
-        def panel_choice
-          return @panel_choice if defined?(@panel_choice)
+        # Subtracts the shared ones so the two cleanup questions never cover the
+        # same directory — they can overlap when the generator runs in ~.
+        def legacy_skill_dirs
+          skill_dirs_in(LEGACY_ROOTS.map { File.expand_path(_1, destination_root) }) - shared_legacy_skill_dirs
+        end
 
-          @panel_choice = if skip_panel?
-            nil
-          else
-            SkillsInstallPanel.new.run
-          end
+        def shared_legacy_skill_dirs
+          skill_dirs_in([File.expand_path(GLOBAL_LEGACY_ROOT)])
         end
 
-        def skip_panel?
-          options[:panel] == false ||
-            options[:quiet] ||
-            options[:path].present? ||
-            options[:only].present? ||
-            !options[:global].nil? ||
-            !SkillsInstallPanel.interactive?
+        # A leftover skill directory, or the scripts/ directory an early 4.1.1
+        # install left behind. A `rm -rf` driven by a name glob alone is not
+        # something to hand a user.
+        def skill_dirs_in(roots)
+          roots.flat_map { |root| Dir.glob(File.join(root, "avo-*")) + Dir.glob(File.join(root, "avo", "scripts")) }
+            .select { |dir| File.directory?(dir) && (File.file?(File.join(dir, "SKILL.md")) || File.basename(dir) == "scripts") }
+            .uniq
+            .sort
         end
 
-        def panel_cancelled?
-          return false unless panel_choice&.cancelled?
+        def removal_command(dirs)
+          "rm -rf #{by_directory(dirs).keys.map { "#{_1}avo-*" }.join(" ")}"
+        end
 
-          say "Cancelled. Nothing was installed.", :yellow
-          true
+        def by_directory(dirs)
+          dirs.group_by { display_dir(_1) }.transform_values(&:count).sort.to_h
         end
 
-        def global_install?
-          return options[:global] unless options[:global].nil?
+        def display_dir(path) = "#{display_path(File.dirname(path))}/"
+
+        def pluralize_skills(count) = "#{count} skill#{"s" unless count == 1}"
 
-          panel_choice&.scope == "global"
+        def display_path(dir)
+          home = File.expand_path("~")
+          return dir.sub(home, "~") if dir.start_with?(home) && !dir.start_with?(File.expand_path(destination_root))
+
+          dir.delete_prefix("#{File.expand_path(destination_root)}/")
         end
       end
     end

data/lib/generators/avo/skills_install_panel.rb

@@ -2,97 +2,184 @@ require "io/console"
 
 module Generators
   module Avo
-    # A small keyboard-driven panel for `rails g avo:skills`.
+    # The `rails g avo:skills` install flow: one question per screen, answered
+    # up front, then the generator runs to completion without interrupting.
     #
-    # Two groups with different semantics: scope is a radio (this app OR the
-    # machine), targets are checkboxes (any combination of scan directories).
-    # Written against io/console from stdlib rather than a prompt gem, because
-    # avo is a dependency of other people's apps and a TUI is not worth adding
-    # one for.
+    # Two screen kinds. A :radio moves its selection with the arrows, so
+    # down-then-enter picks the second option — pressing space to commit a
+    # highlighted row is a step people miss. A :checkbox has an independent
+    # state per row, so there space is the toggle and the arrows only move.
     #
-    # Falls back to defaults whenever there is no interactive terminal, so
-    # `-q`, CI, and piped invocations behave predictably. Callers pass explicit
-    # flags to skip the panel entirely.
+    # Written against io/console from stdlib rather than a prompt gem: avo is a
+    # dependency of other people's apps, and a TUI is not worth adding one for.
     class SkillsInstallPanel
-      SCOPES = [
-        {key: "local", label: "This app", hint: "committed, so the whole team gets it"},
-        {key: "global", label: "This machine", hint: "one install, every Avo project"}
-      ].freeze
-
-      TARGETS = [
-        {key: "claude", label: ".claude/skills", hint: "Claude Code"},
-        {key: "agents", label: ".agents/skills", hint: "Codex, Gemini CLI, Goose, Amp, OpenCode"},
-        {key: "cursor", label: ".cursor/skills", hint: "Cursor"}
-      ].freeze
-
-      Result = Struct.new(:scope, :targets, :cancelled) do
+      # `visible_when` takes the answers so far, so a screen that only makes
+      # sense given an earlier answer is skipped rather than asked pointlessly.
+      # `summary` takes them too, and renders above the options — how the final
+      # confirm screen shows what it is about to do.
+      Screen = Struct.new(:key, :kind, :title, :hint, :options, :visible_when, :summary)
+      Option = Struct.new(:key, :label, :hint, :recommended)
+
+      Result = Struct.new(:answers, :cancelled) do
         def cancelled? = !!cancelled
+
+        def [](key) = answers[key]
       end
 
       def self.interactive?
         $stdin.tty? && $stdout.tty?
       end
 
-      def initialize(input: $stdin, output: $stdout)
+      # `defaults` seeds each screen, including one that never becomes visible —
+      # its default is then simply the answer.
+      def initialize(screens, defaults: {}, input: $stdin, output: $stdout)
+        @screens = screens
         @input = input
         @output = output
-        @scope = 0
-        @targets = TARGETS.map { |t| [t[:key], true] }.to_h
-        @cursor = 0
-        @rows_drawn = 0
-      end
-
-      # Rows are the two scopes then the three targets, so one cursor walks
-      # both groups and the whole panel is arrow-navigable.
-      def rows
-        SCOPES.length + TARGETS.length
+        @answers = {}
+        @screens.each { |s| @answers[s.key] = defaults.fetch(s.key) { initial_for(s) } }
       end
 
+      # `step` carries the direction, so a skipped screen is stepped over the
+      # way it was entered — otherwise going back would walk into it forwards.
       def run
-        render
-        loop do
-          case read_key
-          when :up then move(-1)
-          when :down then move(1)
-          when :space then toggle
-          when :enter then return finish
-          when :cancel then return cancel
+        index = 0
+        step = 1
+
+        while index < @screens.length
+          screen = @screens[index]
+          unless visible?(screen)
+            index += step
+            next
+          end
+
+          case ask(screen, first: first_visible?(index))
+          when :back then step = -1
+          when :cancel then return Result.new({}, true)
+          else step = 1
           end
-          render
+          index += step
         end
+
+        Result.new(@answers, false)
       end
 
       private
 
+      def visible?(screen) = screen.visible_when.nil? || screen.visible_when.call(@answers)
+
+      # Back is only offered when there is an earlier screen still worth
+      # returning to, so a hidden first screen does not strand the user.
+      def first_visible?(index) = @screens[0...index].none? { visible?(_1) }
+
       attr_reader :input, :output
 
-      def move(delta)
-        @cursor = (@cursor + delta) % rows
+      def initial_for(screen)
+        if screen.kind == :radio
+          (screen.options.find(&:recommended) || screen.options.first).key
+        else
+          screen.options.map(&:key)
+        end
       end
 
-      def toggle
-        if @cursor < SCOPES.length
-          @scope = @cursor
-        else
-          key = TARGETS[@cursor - SCOPES.length][:key]
-          # Refuse to empty the set: an install with no target writes nothing
-          # and looks like a silent no-op.
-          @targets[key] = !@targets[key] unless @targets[key] && selected_targets.length == 1
+      def ask(screen, first:)
+        cursor = start_cursor(screen)
+        rows = 0
+
+        loop do
+          rows = draw(screen, cursor, rows, first: first)
+
+          case read_key
+          when :up then cursor = (cursor - 1) % screen.options.length
+          when :down then cursor = (cursor + 1) % screen.options.length
+          when :space then toggle(screen, cursor)
+          when :enter then return commit(screen, cursor, rows)
+          when :back then (return erase(rows) { :back }) unless first
+          when :cancel then return erase(rows) { :cancel }
+          end
+
+          # A radio's selection follows the cursor, so moving is choosing and
+          # enter alone is enough.
+          @answers[screen.key] = screen.options[cursor].key if screen.kind == :radio
         end
       end
 
-      def selected_targets
-        TARGETS.map { |t| t[:key] }.select { |k| @targets[k] }
+      def start_cursor(screen)
+        return 0 unless screen.kind == :radio
+
+        screen.options.index { |o| o.key == @answers[screen.key] } || 0
       end
 
-      def finish
-        clear
-        Result.new(SCOPES[@scope][:key], selected_targets, false)
+      def toggle(screen, cursor)
+        return if screen.kind == :radio
+
+        key = screen.options[cursor].key
+        selected = @answers[screen.key]
+        # Refuse to empty the set: installing nowhere writes nothing and reads
+        # as a silent no-op.
+        return if selected == [key]
+
+        @answers[screen.key] = selected.include?(key) ? selected - [key] : selected + [key]
+        @answers[screen.key] = screen.options.map(&:key).select { |k| @answers[screen.key].include?(k) }
       end
 
-      def cancel
-        clear
-        Result.new(nil, [], true)
+      def commit(screen, cursor, rows)
+        @answers[screen.key] = screen.options[cursor].key if screen.kind == :radio
+        erase(rows) { :next }
+      end
+
+      def erase(rows)
+        output.print("\e[#{rows}A\e[J") if rows.positive?
+        yield
+      end
+
+      def draw(screen, cursor, previous_rows, first:)
+        output.print("\e[#{previous_rows}A\e[J") if previous_rows.positive?
+
+        lines = ["", "  #{bold(screen.title)}"]
+        lines << "  #{dim(screen.hint)}" if screen.hint
+        lines << ""
+
+        if screen.summary
+          screen.summary.call(@answers).each { |line| lines << "    #{line}" }
+          lines << ""
+        end
+
+        screen.options.each_with_index do |option, i|
+          lines << option_row(screen, option, i, cursor)
+        end
+
+        lines << ""
+        lines << "  #{dim(keys_hint(screen, first: first))}"
+        lines << ""
+
+        output.print(lines.join("\n") + "\n")
+        lines.length
+      end
+
+      def option_row(screen, option, index, cursor)
+        marker =
+          if screen.kind == :radio
+            (@answers[screen.key] == option.key) ? "(•)" : "( )"
+          else
+            @answers[screen.key].include?(option.key) ? "[x]" : "[ ]"
+          end
+
+        label = option.label
+        label += " #{dim("(recommended)")}" if option.recommended
+        text = "#{(cursor == index) ? "›" : " "} #{marker} #{label}"
+        text += "  #{dim(option.hint)}" if option.hint
+
+        (cursor == index) ? "  #{bold(text)}" : "  #{text}"
+      end
+
+      def keys_hint(screen, first:)
+        parts = ["↑↓ move"]
+        parts << "space toggle" if screen.kind == :checkbox
+        parts << "enter continue"
+        parts << "← back" unless first
+        parts << "q cancel"
+        parts.join("   ")
       end
 
       def read_key
@@ -100,70 +187,37 @@ module Generators
         case char
         when "\r", "\n" then :enter
         when " " then :space
-        when "", "q", "\e" then escape_or_cancel(char)
+        # nil is EOF: stdin closed, or a test keyboard ran dry. Treat it as
+        # cancel rather than spinning on it forever.
+        when nil, "q", "\u0003", "\u0004" then :cancel
+        when "\e" then escape_sequence
         else :none
         end
       rescue Interrupt
         :cancel
       end
 
-      # An arrow key arrives as ESC [ A. A bare ESC means cancel, so peek at
-      # what follows before deciding.
-      def escape_or_cancel(char)
-        return :cancel unless char == "\e"
+      # Arrows arrive as ESC [ A. A bare ESC cancels, so peek before deciding.
+      def escape_sequence
         return :cancel unless input.respond_to?(:read_nonblock)
 
         begin
           seq = input.read_nonblock(2)
-        rescue IO::WaitReadable, EOFError, Errno::EAGAIN
+        rescue IO::WaitReadable, EOFError, Errno::EAGAIN, Errno::EWOULDBLOCK
           return :cancel
         end
 
         case seq
         when "[A" then :up
         when "[B" then :down
+        when "[D" then :back
         else :none
         end
       end
 
-      def clear
-        output.print("\e[#{@rows_drawn}A\e[J") if @rows_drawn.positive?
-        @rows_drawn = 0
-      end
+      def bold(text) = "\e[1m#{text}\e[0m"
 
-      def render
-        clear
-        lines = []
-        lines << ""
-        lines << "  Install the Avo skills loader"
-        lines << ""
-        lines << "  #{dim("Where")}"
-        SCOPES.each_with_index do |scope, i|
-          lines << row(i, (@scope == i) ? "(•)" : "( )", scope[:label], scope[:hint])
-        end
-        lines << ""
-        lines << "  #{dim("Which agents")}"
-        TARGETS.each_with_index do |target, i|
-          lines << row(SCOPES.length + i, @targets[target[:key]] ? "[x]" : "[ ]", target[:label], target[:hint])
-        end
-        lines << ""
-        lines << "  #{dim("↑↓ move   space select   enter install   q cancel")}"
-        lines << ""
-
-        output.print(lines.join("\n") + "\n")
-        @rows_drawn = lines.length
-      end
-
-      def row(index, marker, label, hint)
-        active = @cursor == index
-        pointer = active ? "›" : " "
-        text = "#{pointer} #{marker} #{label.ljust(16)} #{dim(hint)}"
-        active ? "  \e[1m#{text}\e[0m" : "  #{text}"
-      end
-
-      def dim(text)
-        "\e[2m#{text}\e[0m"
-      end
+      def dim(text) = "\e[2m#{text}\e[0m"
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: avo
 version: !ruby/object:Gem::Version
-  version: 4.1.2
+  version: 4.1.3
 platform: ruby
 authors:
 - Adrian Marin