shapeup-cli 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e3f4bd862f49cc66a46223d4c0f5749a92150d3b2a9fa3a6164933a6bf3970f7
-  data.tar.gz: 2a018829f56a8cbd42679fef24e16a7e8645c22ddeb7b4be2ca6b7b6c3c88211
+  metadata.gz: c4b97dfcf5b4550677ef419ad28ae3900f770c5f3c3795e7b005d2a09582f472
+  data.tar.gz: 8ad78fe52812199514232eadbf8d5e52506e916c391ac6c240ad7730edd6d8fe
 SHA512:
-  metadata.gz: 5857b6c507783ce2dadaaf2fbd6c4df72defe1ea46c09e93e91cec3f9bb74b2e1bfc5dcd4d1a10eddd4b92eece7cb1b6f597e0bd0599841d1947e1682494589b
-  data.tar.gz: d1bfc879a720dd2a486e5a754cecbdb958a8a2bdefe930b9d1a86d34841c625d201ffdf8e151005423cd9813b9533d54db953fbaf59f5877a8874040e6543582
+  metadata.gz: 0467cb5be9b5e7d830406d00495cb9929dfd15772aa7ae09e8abb30237ebceb4e8cc2ad3286e2ef191d5a4186ced7cf900b1d66016edb9f31719a4bead6b06da
+  data.tar.gz: 9a8eea1d289458f647e4c9352a479e8f2bcc726d268a4577e3659c0b4f00132bf0d06a62f8d8f1a5251b01080c69611fe2baea7e0ebe54c53d203ed1432221f7

data/bin/shapeup

@@ -1,6 +1,14 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
+# Guard before requiring any code that uses Ruby 3.x syntax, so users on an
+# old Ruby (e.g. macOS system Ruby 2.6) get a clear message, not a SyntaxError.
+if Gem::Version.new(RUBY_VERSION) < Gem::Version.new("3.1")
+  abort "shapeup requires Ruby 3.1 or newer (you have #{RUBY_VERSION}).\n" \
+        "Install a newer Ruby with Homebrew (brew install ruby), mise, or rbenv, " \
+        "and make sure it comes before /usr/bin in your PATH."
+end
+
 $LOAD_PATH.unshift File.expand_path("../lib", __dir__)
 require "shapeup_cli"
 

data/install.md

@@ -19,22 +19,25 @@ Check if the ShapeUp CLI is available:
 shapeup version
 ```
 
-If `shapeup` is not found, clone the repo and add to PATH:
+If `shapeup` is not found, first check that Ruby 3.1+ is available (`ruby -v`). macOS system Ruby (2.6) is too old — install a newer Ruby with Homebrew (`brew install ruby`), mise, or rbenv, and ensure it comes before `/usr/bin` in PATH.
+
+Then install the gem:
 
 ```bash
-git clone https://github.com/shapeup-cc/shapeup-cli ~/.shapeup-cli
+gem install shapeup-cli
 ```
 
-Add to your shell profile (`~/.zshrc` or `~/.bashrc`):
+If installing the gem is not an option, clone the repo instead and add to your shell profile (`~/.zshrc` or `~/.bashrc`):
 
 ```bash
-alias shapeup='ruby -I~/.shapeup-cli/cli/lib ~/.shapeup-cli/cli/bin/shapeup'
+git clone https://github.com/shapeupcc/shapeup-cli.git ~/.shapeup-cli
+export PATH="$HOME/.shapeup-cli/bin:$PATH"
 ```
 
 **Verify:**
 ```bash
 shapeup version
-# Expected: shapeup 0.1.0
+# Expected: shapeup <version>, e.g. shapeup 0.7.0
 ```
 
 ## Step 1: Authenticate with ShapeUp

data/lib/shapeup_cli/client.rb

@@ -7,6 +7,7 @@ module ShapeupCli
     class NotFoundError < ApiError; end
     class PermissionError < ApiError; end
     class RateLimitError < ApiError; end
+    class NetworkError < ApiError; end
 
     MCP_PROTOCOL_VERSION = "2025-06-18"
 
@@ -66,9 +67,9 @@ module ShapeupCli
       def with_network_error_handling
         yield
       rescue Net::OpenTimeout, Net::ReadTimeout
-        raise ApiError, "The server took too long to respond. Please try again."
+        raise NetworkError, "The server took too long to respond."
       rescue SocketError, Errno::ECONNREFUSED, Errno::EHOSTUNREACH, Errno::ETIMEDOUT => e
-        raise ApiError, "Couldn't reach #{@host} (#{e.class}). Check your connection and 'shapeup config show'."
+        raise NetworkError, "Couldn't reach #{@host} (#{e.class})."
       end
 
       def handle_response(response)

data/lib/shapeup_cli/commands/agents.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module ShapeupCli
+  module Commands
+    class Agents < Base
+      def self.metadata
+        {
+          command: "agents",
+          path: "shapeup agents",
+          short: "List your agents, or add one (Pro, one per member)",
+          subcommands: [
+            { name: "list", short: "List your agents in this organisation", path: "shapeup agents" },
+            { name: "add", short: "Add your agent", path: 'shapeup agents add "Bond" [--handle bond]' }
+          ],
+          flags: [
+            { name: "handle", type: "string", usage: "The agent's handle (default: its name, lowercased)" }
+          ],
+          examples: [
+            "shapeup agents",
+            'shapeup agents add "Bond"',
+            "shapeup connect"
+          ]
+        }
+      end
+
+      def execute
+        case positional_arg(0)
+        when "add" then add
+        else list
+        end
+      end
+
+      private
+        def list
+          render call_tool("list_my_agents"),
+            summary: "Your agents",
+            breadcrumbs: [
+              { cmd: 'shapeup agents add "Name"', description: "Add your agent" },
+              { cmd: "shapeup connect", description: "Listen for requests as your agent" }
+            ]
+        end
+
+        def add
+          handle = extract_option("--handle")
+          name = positional_arg(1) || abort('Usage: shapeup agents add "Name" [--handle handle]')
+
+          arguments = { display_name: name }
+          arguments[:name] = handle if handle
+          render call_tool("add_my_agent", **arguments),
+            summary: "Agent added",
+            breadcrumbs: [ { cmd: "shapeup connect", description: "Listen for requests as your agent" } ]
+        end
+    end
+  end
+end

data/lib/shapeup_cli/commands/comments.rb

@@ -12,13 +12,15 @@ module ShapeupCli
             { name: "list", short: "List comments", path: "shapeup comments list --issue <id>" },
             { name: "add", short: "Add a comment", path: 'shapeup comments add --issue <id> "Comment text"' },
             { name: "edit", short: "Edit your own comment", path: 'shapeup comments edit <comment_id> "New text"' },
-            { name: "remove", short: "Delete your own comment", path: "shapeup comments remove <comment_id>" }
+            { name: "remove", short: "Delete your own comment", path: "shapeup comments remove <comment_id>" },
+            { name: "react", short: "React to a comment with an emoji", path: "shapeup comments react <comment_id> <emoji>" }
           ],
           flags: [
             { name: "issue", type: "string", usage: "Issue ID" },
             { name: "pitch", type: "string", usage: "Pitch ID" },
             { name: "scope", type: "string", usage: "Scope ID" },
-            { name: "task", type: "string", usage: "Task ID" }
+            { name: "task", type: "string", usage: "Task ID" },
+            { name: "parent", type: "string", usage: "Comment ID to reply under" }
           ],
           examples: [
             "shapeup comments list --issue 42",
@@ -38,6 +40,7 @@ module ShapeupCli
         when "add"    then add
         when "edit"   then edit
         when "remove" then remove
+        when "react"  then react
         when "list", nil then list
         else list
         end
@@ -58,9 +61,12 @@ module ShapeupCli
 
         def add
           type, id = resolve_commentable
-          text = positional_arg(1) || abort('Usage: shapeup comments add --issue <id> "Comment text"')
+          parent = extract_option("--parent")
+          text = positional_arg(1) || abort('Usage: shapeup comments add --issue <id> [--parent <comment_id>] "Comment text"')
 
-          result = call_tool("create_comment", commentable_type: type, commentable_id: id.to_s, content: text)
+          arguments = { commentable_type: type, commentable_id: id.to_s, content: text }
+          arguments[:parent_id] = parent.to_s if parent
+          result = call_tool("create_comment", **arguments)
 
           render result,
             summary: "Comment added to #{type} ##{id}",
@@ -88,6 +94,15 @@ module ShapeupCli
           render result, summary: "Comment ##{comment_id} deleted"
         end
 
+        def react
+          comment_id = positional_arg(1) || abort("Usage: shapeup comments react <comment_id> <emoji>")
+          emoji = positional_arg(2) || abort("Usage: shapeup comments react <comment_id> <emoji>")
+
+          result = call_tool("add_reaction", comment_id: comment_id.to_s, emoji: emoji)
+
+          render result, summary: "Reacted #{emoji} to comment ##{comment_id}"
+        end
+
         def resolve_commentable
           issue = extract_option("--issue")
           pitch = extract_option("--pitch")

data/lib/shapeup_cli/commands/config_cmd.rb

@@ -10,6 +10,7 @@ module ShapeupCli
           short: "Show and manage CLI configuration",
           subcommands: [
             { name: "show", short: "Show current config (default)", path: "shapeup config show" },
+            { name: "explain", short: "Trace where each setting's value comes from", path: "shapeup config explain" },
             { name: "set", short: "Set a config value", path: "shapeup config set <key> <value>" },
             { name: "init", short: "Create .shapeup/config.json for this directory", path: "shapeup config init <org>" }
           ],
@@ -30,9 +31,10 @@ module ShapeupCli
         subcommand = positional_arg(0)
 
         case subcommand
-        when "set"  then set
-        when "show" then show
-        when "init" then init_project
+        when "set"     then set
+        when "show"    then show
+        when "explain" then explain
+        when "init"    then init_project
         else show
         end
       end
@@ -96,6 +98,81 @@ module ShapeupCli
           end
         end
 
+        # Trace every setting through its full precedence chain, showing each
+        # candidate and which one won. Token values are never printed.
+        def explain
+          settings = {
+            "profile" => profile_candidates,
+            "org" => org_candidates,
+            "host" => host_candidates,
+            "token" => token_candidates
+          }
+
+          if @mode == :styled || @mode == :markdown
+            settings.each { |name, candidates| print_setting(name, candidates) }
+          else
+            data = settings.transform_values do |candidates|
+              selected = candidates.find { |c| c[:selected] }
+              { value: selected&.dig(:value), source: selected&.dig(:source), candidates: candidates }
+            end
+            render data
+          end
+        end
+
+        def profile_candidates
+          select_first [
+            { source: "SHAPEUP_PROFILE env", value: ENV["SHAPEUP_PROFILE"] },
+            { source: "profiles.json default", value: Config.saved_default_profile }
+          ]
+        end
+
+        def org_candidates
+          select_first [
+            { source: "--org flag", value: @org_id },
+            { source: "SHAPEUP_ORG env", value: ENV["SHAPEUP_ORG"] },
+            { source: project_config_source, value: Config.project_config["organisation_id"] },
+            { source: "~/.config/shapeup/config.json", value: Config.global_config["organisation_id"] },
+            { source: "profile '#{Config.current_profile_name}'", value: Config.current_profile&.dig("organisation_id") }
+          ]
+        end
+
+        def host_candidates
+          select_first [
+            { source: "SHAPEUP_HOST env", value: ENV["SHAPEUP_HOST"] },
+            { source: project_config_source, value: Config.project_config["host"] },
+            { source: "~/.config/shapeup/config.json", value: Config.global_config["host"] },
+            { source: "profile '#{Config.current_profile_name}'", value: Config.current_profile&.dig("host") },
+            { source: "built-in default", value: ShapeupCli::DEFAULT_HOST }
+          ]
+        end
+
+        def token_candidates
+          select_first [
+            { source: "SHAPEUP_TOKEN env", value: ENV["SHAPEUP_TOKEN"] && "configured in environment" },
+            { source: "profile '#{Config.current_profile_name}'", value: Config.current_profile&.dig("token") && "configured in profile" }
+          ]
+        end
+
+        def project_config_source
+          Config.project_config_path || Config::PROJECT_CONFIG_NAME
+        end
+
+        def select_first(candidates)
+          winner = candidates.find { |c| !c[:value].nil? && c[:value] != "" }
+          candidates.each { |c| c[:selected] = c.equal?(winner) }
+        end
+
+        def print_setting(name, candidates)
+          puts name
+          width = candidates.map { |c| c[:source].length }.max
+          candidates.each do |c|
+            marker = c[:selected] ? "  <- selected" : ""
+            value = c[:value].nil? ? "(unset)" : c[:value]
+            puts "  #{c[:source].ljust(width)}  #{value}#{marker}"
+          end
+          puts
+        end
+
         def find_project_display
           dir = Dir.pwd
           loop do

data/lib/shapeup_cli/commands/connect.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module ShapeupCli
+  module Commands
+    class Connect < Base
+      DEFAULT_INTERVAL = 30
+      TRUST_LEVELS = %w[ owner members ].freeze
+
+      def self.metadata
+        {
+          command: "connect",
+          path: "shapeup connect",
+          short: "Listen for requests as your agent, printing each one as a line of JSON",
+          flags: [
+            { name: "as", type: "string", usage: "Which of your agents, by handle (default: your only one)" },
+            { name: "interval", type: "integer", usage: "Seconds between checks (default: #{DEFAULT_INTERVAL})" },
+            { name: "trust", type: "string", usage: "Whose requests to pass on: owner (default) or members" },
+            { name: "once", type: "bool", usage: "Check once and exit" }
+          ],
+          examples: [
+            "shapeup connect",
+            "shapeup connect --as bond --trust members",
+            "SHAPEUP_PROFILE=bond shapeup connect --once"
+          ]
+        }
+      end
+
+      def execute
+        handle = extract_option("--as")
+        @interval = (extract_option("--interval") || DEFAULT_INTERVAL).to_i.clamp(5, 3600)
+        @trust = extract_option("--trust") || "owner"
+        abort "--trust must be one of: #{TRUST_LEVELS.join(", ")}" unless TRUST_LEVELS.include?(@trust)
+        once = consume_flag("--once")
+
+        $stdout.sync = true
+        @handed_out = Set.new
+        @profile, @agent_client = sign_in_as_agent(handle)
+
+        poll(announce: true)
+        until once
+          sleep @interval
+          poll
+        end
+      end
+
+      private
+        def sign_in_as_agent(handle)
+          mine = Output.extract_data(call_tool("list_my_agents"))
+          return [ ENV["SHAPEUP_PROFILE"], client ] if mine["signed_in_as_agent"]
+
+          agent = choose_agent(mine["agents"], handle, can_add: mine["can_add"])
+          token = Output.extract_data(call_tool("issue_my_agent_token", agent: agent["id"].to_s))["token"]
+          Config.save_profile(agent["name"], token: token, host: Config.host, organisation_id: org_id.to_s, display_name: agent["display_name"])
+
+          [ agent["name"], Client.new(host: Config.host, token: token) ]
+        end
+
+        def choose_agent(agents, handle, can_add:)
+          if handle
+            agents.find { |agent| agent["name"] == handle.delete_prefix("@") } or fail_with_agents("You have no agent called @#{handle} here.", agents)
+          elsif agents.one?
+            agents.first
+          elsif agents.none?
+            fail_with_agents(can_add ? 'You don\'t have an agent here yet. Add one with: shapeup agents add "Name"' : "Agents need a Pro organisation where you're a member.", agents)
+          else
+            fail_with_agents("You have several agents here. Pick one with --as <handle>.", agents)
+          end
+        end
+
+        def fail_with_agents(message, agents)
+          emit(type: "error", message: message, retryable: false, agents: agents.map { |agent| agent["name"] })
+          exit EXIT_USAGE
+        end
+
+        def poll(announce: false)
+          inbox = Output.extract_data(@agent_client.call_tool("list_inbox", organisation: org_id.to_s))
+          agent = inbox["agent"]
+
+          emit(type: "connected", agent: agent, profile: @profile, organisation_id: org_id.to_s, trust: @trust, interval: @interval) if announce
+
+          inbox["items"].reverse_each do |item|
+            next unless @handed_out.add?(item["id"])
+
+            if trusted?(item["requester"], agent)
+              emit(type: "request", **item.transform_keys(&:to_sym))
+            else
+              emit(type: "ignored", id: item["id"], requester: item["requester"], why: "#{item["requester"]["name"]} is not trusted (--trust #{@trust})")
+            end
+          end
+        rescue Client::NetworkError, Client::RateLimitError => error
+          emit(type: "error", message: error.message, retryable: true)
+        end
+
+        def trusted?(requester, agent)
+          @trust == "members" || requester["id"] == agent.dig("owner", "id")
+        end
+
+        def emit(**event)
+          puts JSON.generate(event)
+        end
+    end
+  end
+end

data/lib/shapeup_cli/commands/doctor.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+module ShapeupCli
+  module Commands
+    class Doctor < Base
+      Check = Struct.new(:name, :status, :message, :hint, keyword_init: true)
+
+      def self.metadata
+        {
+          command: "doctor",
+          path: "shapeup doctor",
+          short: "Diagnose CLI setup: config, auth, connectivity, and agent skills",
+          subcommands: [],
+          flags: [],
+          notes: [
+            "Each check reports pass, warn, fail, or skip with a fix hint",
+            "Exits 0 when nothing failed, 1 otherwise"
+          ],
+          examples: [ "shapeup doctor", "shapeup doctor --json" ]
+        }
+      end
+
+      def execute
+        checks = [
+          check_cli_version,
+          check_ruby_version,
+          check_config_dir,
+          check_profiles_file,
+          check_config_file,
+          check_project_config,
+          check_token,
+          check_host_url,
+          check_api_reachable,
+          check_auth,
+          check_org_access,
+          check_claude_skill
+        ]
+
+        report(checks)
+        exit 1 if checks.any? { |c| c.status == :fail }
+      end
+
+      private
+        def check_cli_version
+          pass "cli", "shapeup #{VERSION}"
+        end
+
+        def check_ruby_version
+          pass "ruby", RUBY_VERSION
+        end
+
+        def check_config_dir
+          if File.directory?(Config::CONFIG_DIR)
+            File.writable?(Config::CONFIG_DIR) ?
+              pass("config dir", Config::CONFIG_DIR) :
+              fail!("config dir", "#{Config::CONFIG_DIR} is not writable")
+          else
+            warn! "config dir", "#{Config::CONFIG_DIR} does not exist yet", hint: "shapeup login"
+          end
+        end
+
+        def check_profiles_file
+          return warn!("profiles", "no profiles saved", hint: "shapeup login") unless File.exist?(Config::PROFILES_FILE)
+
+          data = JSON.parse(File.read(Config::PROFILES_FILE))
+          names = (data["profiles"] || {}).keys
+          pass "profiles", "#{names.length} saved (default: #{data["default"] || "none"})"
+        rescue JSON::ParserError
+          fail! "profiles", "#{Config::PROFILES_FILE} is not valid JSON", hint: "shapeup logout"
+        end
+
+        def check_config_file
+          return pass("global config", "(none)") unless File.exist?(Config::CONFIG_FILE)
+
+          JSON.parse(File.read(Config::CONFIG_FILE))
+          pass "global config", Config::CONFIG_FILE
+        rescue JSON::ParserError
+          fail! "global config", "#{Config::CONFIG_FILE} is not valid JSON"
+        end
+
+        def check_project_config
+          path = Config.project_config_path
+          return skip("project config", "none found") unless path
+
+          JSON.parse(File.read(path))
+          pass "project config", path
+        rescue JSON::ParserError
+          fail! "project config", "#{path} is not valid JSON"
+        end
+
+        def check_token
+          if ENV["SHAPEUP_TOKEN"]
+            pass "token", "from SHAPEUP_TOKEN"
+          elsif Config.current_profile&.dig("token")
+            pass "token", "from profile '#{Config.current_profile_name}'"
+          else
+            fail! "token", "no credentials found", hint: "shapeup login"
+          end
+        end
+
+        def check_host_url
+          uri = URI.parse(Config.host)
+          if uri.is_a?(URI::HTTP) && uri.host
+            pass "host", Config.host
+          else
+            fail! "host", "#{Config.host.inspect} is not a valid URL", hint: "shapeup config set host <url>"
+          end
+        rescue URI::InvalidURIError
+          fail! "host", "#{Config.host.inspect} is not a valid URL", hint: "shapeup config set host <url>"
+        end
+
+        def check_api_reachable
+          uri = URI.parse("#{Config.host}/up")
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = uri.scheme == "https"
+          http.open_timeout = 5
+          http.read_timeout = 5
+          response = http.get(uri.path)
+
+          response.code.to_i < 500 ?
+            pass("server", "#{Config.host} reachable") :
+            fail!("server", "#{Config.host} responded with HTTP #{response.code}")
+        rescue StandardError => e
+          fail! "server", "couldn't reach #{Config.host} (#{e.class})", hint: "shapeup config explain"
+        end
+
+        def check_auth
+          return skip("auth", "no token to test") unless Config.token
+
+          result = Output.extract_data(Client.new.call_tool("list_organisations"))
+          @organisations = result.is_a?(Hash) ? (result["organisations"] || []) : Array(result)
+          pass "auth", "signed in, #{@organisations.length} organisation(s)"
+        rescue Client::AuthError
+          fail! "auth", "token was rejected", hint: "shapeup login"
+        rescue Client::ApiError => e
+          fail! "auth", e.message
+        end
+
+        def check_org_access
+          return skip("org", "auth not verified") unless @organisations
+
+          org = Config.organisation_id
+          return warn!("org", "no default organisation set", hint: "shapeup config set org <name>") unless org
+
+          if @organisations.any? { |o| o["id"].to_s == org.to_s }
+            pass "org", "##{org} accessible"
+          else
+            fail! "org", "##{org} is not among your organisations", hint: "shapeup orgs"
+          end
+        end
+
+        def check_claude_skill
+          installed = File.join(Dir.home, ".claude", "skills", "shapeup", "SKILL.md")
+          return warn!("claude skill", "not installed", hint: "shapeup setup claude") unless File.exist?(installed)
+
+          if File.read(installed) == File.read(Setup::SKILL_SOURCE)
+            pass "claude skill", "installed and current"
+          else
+            warn! "claude skill", "installed but stale", hint: "shapeup setup claude"
+          end
+        end
+
+        def pass(name, message) = Check.new(name: name, status: :pass, message: message)
+        def warn!(name, message, hint: nil) = Check.new(name: name, status: :warn, message: message, hint: hint)
+        def fail!(name, message, hint: nil) = Check.new(name: name, status: :fail, message: message, hint: hint)
+        def skip(name, message) = Check.new(name: name, status: :skip, message: message)
+
+        STATUS_MARKS = { pass: "ok", warn: "!!", fail: "XX", skip: "--" }.freeze
+
+        def report(checks)
+          counts = checks.group_by(&:status).transform_values(&:length)
+          summary = "#{counts.fetch(:pass, 0)} passed, #{counts.fetch(:warn, 0)} warnings, #{counts.fetch(:fail, 0)} failed, #{counts.fetch(:skip, 0)} skipped"
+          breadcrumbs = checks.select { |c| c.hint }.map { |c| { cmd: c.hint, description: "fix: #{c.name}" } }
+
+          if @mode == :styled
+            width = checks.map { |c| c.name.length }.max
+            checks.each do |c|
+              line = "  #{STATUS_MARKS[c.status]}  #{c.name.ljust(width)}  #{c.message}"
+              line += "  (#{c.hint})" if c.hint
+              puts line
+            end
+            puts
+            puts summary
+            if breadcrumbs.any?
+              puts
+              puts "Next:"
+              breadcrumbs.each { |b| puts "  #{b[:cmd]}  # #{b[:description]}" }
+            end
+          else
+            render({ "checks" => checks.map { |c| c.to_h.compact }, "summary" => counts },
+              breadcrumbs: breadcrumbs, summary: summary)
+          end
+        end
+    end
+  end
+end

data/lib/shapeup_cli/commands/inbox.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module ShapeupCli
+  module Commands
+    class Inbox < Base
+      def self.metadata
+        {
+          command: "inbox",
+          path: "shapeup inbox",
+          short: "For agents: requests waiting on issues, and marking them done",
+          subcommands: [
+            { name: "list", short: "List requests waiting for this agent", path: "shapeup inbox" },
+            { name: "done", short: "Take a handled request out of the inbox", path: "shapeup inbox done <id>" }
+          ],
+          examples: [
+            "shapeup inbox",
+            "shapeup inbox --json",
+            "shapeup inbox done 812"
+          ]
+        }
+      end
+
+      def execute
+        case positional_arg(0)
+        when "done" then done
+        else list
+        end
+      end
+
+      private
+        def list
+          result = call_tool("list_inbox")
+
+          render result,
+            summary: "Inbox",
+            breadcrumbs: [
+              { cmd: "shapeup issue <id>", description: "Read the issue in full" },
+              { cmd: 'shapeup comments add --issue <id> "Reply"', description: "Reply on the issue" },
+              { cmd: "shapeup inbox done <id>", description: "Mark a request handled" }
+            ]
+        end
+
+        def done
+          id = positional_arg(1) || abort("Usage: shapeup inbox done <id>")
+          result = call_tool("complete_inbox_item", item: id.to_s)
+
+          render result, summary: "Request #{id} done"
+        end
+    end
+  end
+end