slk 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 54edc7e40c9bcf891e2d2727c4cf50c4f43de73a70051465da12f3a97bc5282b
-  data.tar.gz: 40bbb5862b982c4e0d87d2a47c18b91a2f0070cac9fe7ad15a68e109114bf977
+  metadata.gz: 895e4fdd405a7b4f560424a93d4906ea7330088763a5559b2d581788908794b3
+  data.tar.gz: 6f8c66d9cd6555153db454d99d7cafdf4e82bbaac2f6349edee1427047e31104
 SHA512:
-  metadata.gz: 96abfcac2a271dccbce0a7b8068d23cf70d62ff68466e2a915fd67474aa9a3b6f648dce14ebaa87718c069993886a309c86490ab865a060586789bf8f8775752
-  data.tar.gz: ece446478a9dfda1dec3fa5dad6feff79c5f7be24e89f9835d61a0f3684e3d7839a94c673859ac5678a1f0f0c8675d31a9673493e744efcdd67433acda1f8fda
+  metadata.gz: 7394318fac53168225d5ff30a249612a0f756fe60eaca67141ca937d43f8c70aaa7a1066681bb35a97fc49f242254d87438f369b02700193cc86456ded97ca9c
+  data.tar.gz: ea890ffc51e6540c6a19db3481d92b8f0263c042594f74c4ec2ac3f975c7f988d345f69e0a6b37345993b499535180b87456cd189dffa9506b2c60148f2b9481

data/CHANGELOG.md

@@ -5,7 +5,86 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.7.0] - 2026-08-03
+
+### Added
+
+- **`slk status schedule|scheduled|unschedule`** — queue statuses to turn on later
+  - `slk status schedule "<text>" [:emoji:] <start-end>` schedules a status; emoji defaults to `:speech_balloon:`
+  - Time windows accept bare 12- or 24-hour times (`1:30p-3:30p`, `13:30-15:30`) or an explicit `YYYY-MM-DD` date (`2026-08-04 9:00-17:00`)
+  - Bare times resolve forward: a window at or before now rolls to tomorrow, and an end before the start crosses midnight (`11p-1a`)
+  - A single am/pm carries across the range, so `1-3p` is 1pm to 3pm — unless that would invert it, leaving `9-5p` as 9am to 5pm
+  - Ambiguous or impossible windows are rejected rather than guessed: `9-5` and `9a-5` (both read as crossing midnight and spanning 20 hours), `1p-1p`, a time DST skips, and unrecognized date forms such as `8/4` or `tomorrow`
+  - The check applies only to a reading that had to be guessed, and only past 12 hours, so windows that say what they mean still work: `11p-1a`, `8p-9a`, `20:00-09:00`, `20:00-6`, and `9p-5`
+  - `--start WHEN` / `--end WHEN` take `[YYYY-MM-DD ]TIME` each, for windows the single-date range cannot express: `--start "2026-08-12 8a" --end "2026-08-14 5p"`. Omitting `--end` schedules a status with no expiry
+  - `--with-dnd` also pauses notifications while the status is active
+  - `slk status scheduled` lists pending statuses with their IDs across every workspace; `slk status unschedule <id>` looks up which workspace owns the ID rather than assuming the primary one (`-w`/`--all` still override)
+  - `slk status scheduled` marks the one Slack reports as currently applied with `[active]`
+  - Backed by Slack's internal `users.customStatus.*` endpoints, which require form-encoded bodies and only return the scheduled section when `statuses_count_per_section` is sent. Responses are checked rather than trusted: an absent `scheduled_statuses` section, a create that echoes nothing back, a status payload with no id, and a delete the following list still shows all raise instead of reporting success
+
+### Changed
+
+- New `Slk::UsageError` (bad invocation) and `Slk::TimeFormatError` (unparseable time) error types. `slk` prints them without an error-type label, and callers can rescue malformed input without also swallowing arity or range errors from their own code
+- Flags that take a value now reject a missing one or a following flag instead of shifting `nil`. This covers `--start`, `--end`, `-p` and `-d` on `status`, and `-w`/`--workspace` everywhere — a trailing `slk status -w` previously applied to *every* workspace and exited 0
+
+### Fixed
+
+- `slk status unschedule` no longer reports a successful cancel as a failure when the confirming re-read fails (a network error, a rate limit, or Slack dropping the `scheduled_statuses` section — which is exactly what happens when you cancel your only scheduled status). The cancel is reported with an explicit "could not confirm" caveat and exit 0; only a status still demonstrably present is an error
+- `slk status schedule` again reports an unusable Slack response as "check the status picker to see whether it was created" rather than the less actionable "returned a scheduled status with no id"
+- `Slk::UsageError` no longer files a backtrace in `~/.cache/slk/error.log`; a mistyped flag is not a fault to investigate later
+- SSH key validation no longer hangs on Windows when the private key is passphrase-protected. `ssh-keygen` prompts on the console rather than on stdin, so the prompt could not be answered or dismissed; it is now given an empty passphrase up front and reports the unsupported key instead of waiting
+
+## [0.6.0] - 2026-04-27
+
+### Added
+
+- **`slk who [target]`** — compact teems-style profile card for self or any user
+  - Targets: positional arg accepts `Uxxx`, display name, real name, or email; defaults to self
+  - `--full` expands into Contact / People / About me sections matching the Slack web profile
+  - `--json` emits the full Profile struct for piping
+  - `--refresh` bypasses both the per-run memo and the on-disk meta cache
+  - `--all` prints every match in turn; `--pick N` picks the Nth match non-interactively
+  - Multi-match disambiguation: prints a numbered list on stderr and prompts on a TTY; non-TTY contexts raise instead of silently picking
+  - Renders Slack Connect external users with a stripped layout (`external — <home workspace>`)
+  - Marks deactivated accounts with a bold `deactivated account` tag (and `deactivated: true` in JSON)
+  - Type-aware custom field rendering: `link` fields use OSC 8 hyperlinks with their `alt` label, `date` fields show "Jun 17, 2024 (1y 10mo ago)", `user` fields resolve one level (name + pronouns + title)
+- **`slk org [target]`** — walks the supervisor chain upward from the target
+  - `--depth N` caps traversal (default 5); cycle-safe via seen-set
+  - Indented tree with `└─ ├─ │` glyphs; `← you` marker on whichever node is the authenticated user
+- New `Api::Team` wrapper for `team.info` and `team.profile.get`, plus `Api::Users#profile_for(user_id, include_labels:)`
+- `Services::ProfileResolver`, `ProfileBuilder`, `UserMatcher`, `UserPicker`, `WhoTargetResolver`, `MetaCache` services backing the new commands
+- Hidden `slk debug profile <uid>` subcommand for inspecting raw profile/info/schema responses
+
+### Changed
+
+- `ApiError` now carries a typed `code` symbol (`:user_not_found`, `:ratelimited`, `:network_error`, `:unauthorized`, `:http_error`, `:invalid_json`, `:missing_scope`); `ApiClient` populates it on every raise
+- `ProfileResolver` only swallows `:user_not_found` from `users.profile.get` (Slack Connect fallback to `users.info`); other API errors propagate so callers can surface them
+- CI matrix now uses `bundler-cache` and runs `bundle exec rake test`; new `coverage` job enforces a 95/95 line/branch SimpleCov threshold
+- Pinned `parallel < 2.0` in dev/test bundle to keep Ruby 3.2 compatible with current rubocop
+
+### Fixed
+
+- `slk org` no longer mislabels the wrong node with `← you` when invoked against a teammate — the marker now compares each node against the authenticated user id
+
+## [0.5.0] - 2026-04-13
+
+### Added
+
+- **`--fetch-attachments` flag** - Download message files and attachment images to local cache
+  - Downloads Slack files (authed) and public attachment images (Giphy, Tenor, etc.)
+  - Cached to `~/.cache/slk/files/{workspace}/` with skip-on-rerun
+  - Shows copyable local file paths in output: `[File: /path/to/file.png]`
+  - Works with `messages`, `thread`, and `--threads` inline replies
+  - Summary line when files are present: `9 files not downloaded. Use --fetch-attachments to download.`
+  - Follows up to 3 redirect hops with relative URL resolution
+
+### Changed
+
+- Added `rubocop` as a dev dependency for linting
+
+### Fixed
+
+- **`thread` command** - Extracted `resolve_and_display_thread` to fix rubocop complexity warnings
 
 ## [0.4.2] - 2026-03-01
 
@@ -131,6 +210,9 @@ Initial release of the Ruby rewrite. Pure Ruby, no external dependencies.
   - Pure Ruby stdlib - no gem dependencies
   - Ruby 3.2+ with modern features (Data.define, pattern matching)
 
+[0.7.0]: https://github.com/ericboehs/slk/releases/tag/v0.7.0
+[0.6.0]: https://github.com/ericboehs/slk/releases/tag/v0.6.0
+[0.5.0]: https://github.com/ericboehs/slk/releases/tag/v0.5.0
 [0.4.2]: https://github.com/ericboehs/slk/releases/tag/v0.4.2
 [0.4.0]: https://github.com/ericboehs/slk/releases/tag/v0.4.0
 [0.3.0]: https://github.com/ericboehs/slk/releases/tag/v0.3.0

data/README.md

@@ -52,6 +52,37 @@ slk status "In a meeting" :calendar: 1h # Set status for 1 hour
 slk status clear                        # Clear status
 ```
 
+Statuses can also be scheduled to turn on later (Slack allows up to 5 at a time):
+
+```bash
+slk status schedule "Vet Appt" :paw_prints: 1:30p-3:30p       # Bare times; rolls to tomorrow if past
+slk status schedule "OOO" :palm_tree: 2026-08-04 9:00-17:00   # Explicit date
+slk status schedule "Heads down" :no_bell: 11p-1a --with-dnd  # Overnight, pausing notifications
+slk status scheduled                                          # List pending (all workspaces)
+slk status unschedule CS0BMQDDGWTU                            # Cancel one (finds the owning workspace)
+```
+
+A single am/pm carries across the range, so `1-3p` is 1pm to 3pm — unless that
+would invert it, leaving `9-5p` as 9am to 5pm. Anything the am/pm cannot settle
+is read as a 24-hour time, which is usually right but occasionally means the
+opposite of what you typed: `9-5` and `9a-5` both come out as 9am until 5am the
+next morning. Windows that land that way — guessed, crossing midnight, and over
+12 hours — are rejected rather than scheduled, so add the second am/pm (`9a-5p`)
+or use 24-hour times (`9:00-17:00`).
+
+Overnight windows are fine when they say so. A meridiem on both sides (`11p-1a`,
+`8p-9a`) or a 24-hour time on either side (`20:00-09:00`, `20:00-6`) settles the
+range, and a pm start is enough on its own: `9p-5` is 9pm to 5am.
+
+A `start-end` range writes the date once and the end can only reach the next
+day, so multi-day windows use `--start` / `--end` instead. Each takes
+`[YYYY-MM-DD ]TIME`, and omitting `--end` schedules a status with no expiry:
+
+```bash
+slk status schedule "OOO" :palm_tree: --start "2026-08-12 8a" --end "2026-08-14 5p"
+slk status schedule "Heads down" :no_bell: --start 2p         # Stays until cleared
+```
+
 ### Presence
 
 ```bash

data/lib/slk/api/custom_status.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Slk
+  module Api
+    # Wrapper for Slack's internal users.customStatus.* endpoints, which back
+    # the "Scheduled" section of the status picker.
+    #
+    # Two undocumented quirks these methods paper over:
+    #   - Only form-encoded bodies are accepted. A JSON body is ignored and the
+    #     call fails with invalid_arguments naming every field as missing.
+    #   - list omits scheduled_statuses entirely unless
+    #     statuses_count_per_section is passed.
+    class CustomStatus
+      DEFAULT_SECTION_COUNT = 20
+
+      def initialize(api_client, workspace)
+        @api = api_client
+        @workspace = workspace
+      end
+
+      # @return [Hash] raw response; 'statuses' (recent) and 'scheduled_statuses'
+      #   (pending) are each absent when Slack omits the section
+      def list(count_per_section: DEFAULT_SECTION_COUNT)
+        @api.post_form(@workspace, 'users.customStatus.list',
+                       { statuses_count_per_section: count_per_section.to_s })
+      end
+
+      # @return [Array<Models::ScheduledStatus>] pending statuses only
+      def scheduled(count_per_section: DEFAULT_SECTION_COUNT)
+        response = list(count_per_section: count_per_section)
+        section = response['scheduled_statuses']
+        # An absent section is a protocol change, not an empty list. Reporting
+        # it as "none scheduled" would invite the user to re-create statuses
+        # that still exist.
+        unless section.is_a?(Array)
+          raise ApiError.new('Slack returned no scheduled_statuses section; this internal endpoint may have changed. ' \
+                             'Check the Slack status picker before re-scheduling.',
+                             code: :missing_scheduled_section)
+        end
+
+        section.map { |item| Models::ScheduledStatus.from_api(item) }
+      end
+
+      # @param date_scheduled [Integer] Unix timestamp the status turns on
+      # @param date_expire [Integer, nil] Unix timestamp it clears
+      # @param dnd [Boolean] also pause notifications while active
+      # @return [Models::ScheduledStatus]
+      def schedule(text:, emoji:, date_scheduled:, date_expire: nil, dnd: false)
+        params = { text: text, emoji: emoji, date_scheduled: date_scheduled.to_i.to_s }
+        params[:date_expire] = date_expire.to_i.to_s if date_expire
+        params[:is_dnd] = 'true' if dnd
+
+        response = @api.post_form(@workspace, 'users.customStatus.schedule', params)
+        Models::ScheduledStatus.from_api(confirmed_schedule(response))
+      end
+
+      # Slack answers a delete with ok: true whether or not anything changed —
+      # including for an id that never existed — so the response alone is not
+      # evidence. Re-reading the list at least catches an accepted delete that
+      # did not apply. It cannot distinguish "cancelled" from "was never
+      # there": both leave the id absent. `unschedule` covers that case ahead
+      # of time by finding the workspace that owns the id.
+      #
+      # @return [Array(Symbol, String, nil)] `[:cancelled, nil]`, or
+      #   `[:unconfirmed, reason]` when the delete was accepted but the
+      #   following read failed. Those are different things: only the second
+      #   read failed, and reporting it as a failed *cancel* would send the
+      #   user back to re-cancel something already gone.
+      # @raise [ApiError] only when the status is demonstrably still there
+      def delete_scheduled(custom_status_id)
+        @api.post_form(@workspace, 'users.customStatus.deleteScheduled',
+                       { custom_status_id: custom_status_id })
+        confirm_deleted(custom_status_id)
+      end
+
+      private
+
+      # The delete has already been accepted by the time this runs, so this
+      # only decides how much can honestly be said about it. A read that
+      # fails — including a rate-limited one, since the confirming read hits
+      # the same `list` method a multi-workspace sweep just used — is a
+      # failure to look, not a failure to delete.
+      def confirm_deleted(custom_status_id)
+        return [:cancelled, nil] unless scheduled.any? { |status| status.id == custom_status_id }
+
+        raise ApiError.new("Slack reported success but #{custom_status_id} is still scheduled.",
+                           code: :delete_not_applied)
+      rescue ApiError => e
+        raise if e.code == :delete_not_applied
+
+        [:unconfirmed, e.message]
+      end
+
+      # A create that reports ok without echoing back the status it made has
+      # not demonstrably created anything.
+      #
+      # The id check duplicates ScheduledStatus.validate!, deliberately:
+      # letting an id-less payload through to that guard trades this message
+      # for "Slack returned a scheduled status with no id: {}", which tells
+      # the user nothing they can act on. Here the answer is the same either
+      # way — go look at the picker.
+      def confirmed_schedule(response)
+        payload = response['scheduled_status']
+        return payload if payload.is_a?(Hash) && !payload['id'].to_s.empty?
+
+        raise ApiError.new('Slack accepted the request but returned no scheduled status, so nothing was confirmed. ' \
+                           'Check the Slack status picker to see whether it was created.',
+                           code: :malformed_schedule_response)
+      end
+    end
+  end
+end

data/lib/slk/api/team.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Slk
+  module Api
+    # Wrapper for Slack team.* API endpoints
+    class Team
+      def initialize(api_client, workspace)
+        @api = api_client
+        @workspace = workspace
+      end
+
+      def info(team_id = nil)
+        params = team_id ? { team: team_id } : {}
+        @api.post_form(@workspace, 'team.info', params)
+      end
+
+      def profile_schema(visibility: nil)
+        params = {}
+        params[:visibility] = visibility if visibility
+        @api.post_form(@workspace, 'team.profile.get', params)
+      end
+    end
+  end
+end

data/lib/slk/api/users.rb

@@ -49,6 +49,10 @@ module Slk
         }
       end
 
+      def get_presence_for(user_id)
+        @api.post_form(@workspace, 'users.getPresence', { user: user_id })
+      end
+
       def set_presence(presence) # rubocop:disable Naming/AccessorMethodName
         @api.post(@workspace, 'users.setPresence', { presence: presence })
       end
@@ -63,6 +67,12 @@ module Slk
         @api.post_form(@workspace, 'users.info', { user: user_id })
       end
 
+      def profile_for(user_id, include_labels: true)
+        params = { user: user_id }
+        params[:include_labels] = true if include_labels
+        @api.post_form(@workspace, 'users.profile.get', params)
+      end
+
       def get_prefs # rubocop:disable Naming/AccessorMethodName
         @api.post(@workspace, 'users.prefs.get')
       end

data/lib/slk/cli.rb

@@ -20,7 +20,10 @@ module Slk
       'cache' => Commands::Cache,
       'emoji' => Commands::Emoji,
       'config' => Commands::Config,
-      'help' => Commands::Help
+      'help' => Commands::Help,
+      'debug' => Commands::Debug,
+      'who' => Commands::Who,
+      'org' => Commands::Org
     }.freeze
 
     def initialize(argv, output: nil)
@@ -69,7 +72,7 @@ module Slk
       else
         show_unknown_command(command_name)
       end
-    rescue ConfigError, EncryptionError, ApiError => e
+    rescue ConfigError, EncryptionError, ApiError, UsageError => e
       handle_known_error(e)
     end
 
@@ -83,7 +86,10 @@ module Slk
     def handle_known_error(error)
       label = error_label(error)
       @output.error(label ? "#{label}: #{error.message}" : error.message)
-      log_error(error)
+      # error.log exists to investigate faults after the fact. A mistyped flag
+      # or an unparseable time is not one, and filing a backtrace for it both
+      # buries the real entries and contradicts what UsageError promises.
+      log_error(error) unless error.is_a?(UsageError)
       1
     end
 
@@ -140,6 +146,11 @@ module Slk
       runner.api_client.on_request = lambda { |method, count|
         output.debug("[API ##{count}] #{method}")
       }
+      runner.api_client.on_response = lambda { |method, code, headers|
+        next unless code == 'rate-wait'
+
+        output.warn("Rate limited on #{method}; sleeping #{headers['sleep_seconds']}s and retrying...")
+      }
     end
 
     def setup_very_verbose_logging(runner, output)

data/lib/slk/commands/base.rb

@@ -65,7 +65,7 @@ module Slk
       # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
       def parse_single_option(arg, args, remaining)
         case arg
-        when '-w', '--workspace' then @options[:workspace] = args.shift
+        when '-w', '--workspace' then @options[:workspace] = option_value(arg, args)
         when '--width' then parse_width_option(args)
         when '--no-wrap' then @options[:width] = nil
         when '--all' then @options[:all] = true
@@ -93,6 +93,18 @@ module Slk
 
       protected
 
+      # A bare `args.shift` returns nil for a trailing flag, which then reads
+      # as an option nobody set: `slk status -w` selected *every* workspace
+      # and exited 0, the opposite of what it says. A following flag is the
+      # same mistake one token later — `--end --with-dnd` would take
+      # "--with-dnd" as the time.
+      def option_value(flag, args)
+        value = args.first
+        raise UsageError, "#{flag} requires a value." if value.nil? || value.start_with?('-')
+
+        args.shift
+      end
+
       # Override in subclass to handle command-specific options
       # Return true if option was handled, false to raise unknown option error
       def handle_option(arg, _args, _remaining) # rubocop:disable Naming/PredicateMethod

data/lib/slk/commands/debug.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Slk
+  module Commands
+    # Hidden command for development spikes.
+    # Dumps raw JSON from Slack endpoints to validate xoxc compatibility
+    # and field shapes before building higher-level features.
+    #
+    # Not registered in `slk help`.
+    class Debug < Base
+      def execute
+        result = validate_options
+        return result if result
+
+        dispatch_action
+      rescue ApiError => e
+        error("API error: #{e.message}")
+        1
+      end
+
+      def dispatch_action
+        case positional_args
+        in ['profile', user] then dump_profile(user)
+        in ['profile'] then dump_profile(nil)
+        in ['team'] then dump_team
+        in ['schema'] then dump_schema
+        else unknown_action
+        end
+      end
+
+      private
+
+      def dump_profile(user_input)
+        workspace = runner.workspace(@options[:workspace])
+        user_id = resolve_user_id(workspace, user_input)
+        users_api = runner.users_api(workspace.name)
+        out = {
+          'users.profile.get' => users_api.profile_for(user_id),
+          'users.info' => users_api.info(user_id),
+          'team.profile.get' => runner.team_api(workspace.name).profile_schema
+        }
+        output.puts(JSON.pretty_generate(out))
+        0
+      end
+
+      def dump_team
+        workspace = runner.workspace(@options[:workspace])
+        output.puts(JSON.pretty_generate(runner.team_api(workspace.name).info))
+        0
+      end
+
+      def dump_schema
+        workspace = runner.workspace(@options[:workspace])
+        output.puts(JSON.pretty_generate(runner.team_api(workspace.name).profile_schema))
+        0
+      end
+
+      def resolve_user_id(workspace, user_input)
+        return self_user_id(workspace) if user_input.nil? || user_input == 'me'
+        return user_input if user_input.match?(/\A[UW][A-Z0-9]+\z/)
+
+        id = lookup_for(workspace).find_id_by_name(user_input.delete_prefix('@'))
+        raise ApiError, "Could not resolve user: #{user_input}" unless id
+
+        id
+      end
+
+      def lookup_for(workspace)
+        Services::UserLookup.new(
+          cache_store: cache_store,
+          workspace: workspace,
+          api_client: api_client,
+          on_debug: ->(msg) { output.debug(msg) }
+        )
+      end
+
+      def self_user_id(workspace)
+        client = Api::Client.new(api_client, workspace)
+        response = client.auth_test
+        response['user_id']
+      end
+
+      def unknown_action
+        error("Unknown debug action: #{positional_args.first.inspect}")
+        error('Valid actions: profile [user], team, schema')
+        1
+      end
+
+      protected
+
+      def help_text
+        <<~HELP
+          slk debug <action> [args]
+
+          Hidden development command — dumps raw API responses for spike validation.
+
+          ACTIONS
+            profile [user]   Dump users.profile.get + users.info + team.profile.get
+            team             Dump team.info
+            schema           Dump team.profile.get
+
+          USER
+            (none) | me      Self
+            @handle | name   Resolved via user cache
+            Uxxx             Raw user ID
+        HELP
+      end
+    end
+  end
+end

data/lib/slk/commands/help.rb

@@ -74,6 +74,7 @@ module Slk
             slk status                       Show current status
             slk status "Working" :laptop:    Set status
             slk status clear                 Clear status
+            slk status schedule "Vet" 1p-3p  Schedule a status (am/pm or 24h)
             slk dnd 1h                       Enable DND for 1 hour
             slk messages #general            Read channel messages
             slk preset meeting               Apply preset

data/lib/slk/commands/org.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Slk
+  module Commands
+    # Walk the Slack org chart by following Supervisor custom profile fields.
+    # Examples:
+    #   slk org                        # self, supervisors up to depth 3
+    #   slk org @alex                  # alex's chain
+    #   slk org Uxxx --depth 5
+    #   slk org --down                 # reports (best-effort, requires reindex for completeness)
+    class Org < Base
+      DEFAULT_DEPTH = 5
+
+      def execute
+        result = validate_options
+        return result if result
+
+        run
+      rescue ApiError => e
+        error("API error: #{e.message}")
+        1
+      end
+
+      protected
+
+      def handle_option(arg, args, _remaining)
+        case arg
+        when '--up' then @options[:direction] = :up
+        when '--down' then @options[:direction] = :down
+        when '--depth' then @options[:depth] = args.shift.to_i
+        else return super
+        end
+        true
+      end
+
+      def help_text
+        <<~HELP
+          slk org [target]
+
+          Walk the Slack org chart by Supervisor field.
+
+          OPTIONS
+            --up               Walk supervisors upward (default)
+            --down             Show direct reports (best-effort, see note)
+            --depth N          Levels to walk (default #{DEFAULT_DEPTH})
+
+          NOTES
+            --down currently scans cached profiles only. Run `slk who` on a
+            user to seed their profile in cache; full crawl support is TODO.
+        HELP
+      end
+
+      private
+
+      def run
+        workspace = runner.workspace(@options[:workspace])
+        resolver = runner.profile_resolver(workspace.name, refresh: @options[:refresh])
+        user_id = resolve_user_id(workspace)
+        target = resolver.resolve(user_id)
+        @self_user_id = self_user_id(workspace)
+
+        case @options[:direction] || :up
+        when :up then render_up(resolver, target)
+        when :down then render_down(target)
+        end
+        0
+      end
+
+      def render_up(resolver, target)
+        chain = resolver.resolve_chain_up(target.user_id, depth: @options[:depth] || DEFAULT_DEPTH)
+        if chain.empty?
+          info("No supervisor on #{target.best_name}'s profile.")
+          return
+        end
+
+        chain.reverse_each.with_index do |profile, depth|
+          render_node(profile, depth, you: profile.user_id == @self_user_id)
+        end
+        render_node(target, chain.size, you: target.user_id == @self_user_id)
+      end
+
+      def render_down(target)
+        warn('slk org --down is best-effort against cached profiles only.')
+        warn('Run `slk who <user>` to seed their profile, or wait for `slk org reindex` (TODO).')
+        info("Direct reports for #{target.best_name}: lookup not yet wired (Phase 4).")
+      end
+
+      def render_node(profile, depth, you: false)
+        prefix = depth.zero? ? '' : "#{'  ' * depth}└─ "
+        marker = you ? output.bold(' ← you') : ''
+        title = profile.title.to_s.empty? ? '' : " — #{output.gray(profile.title)}"
+        output.puts("#{prefix}#{profile.best_name}#{title}#{marker}")
+      end
+
+      def resolve_user_id(workspace)
+        target = positional_args.first
+        return self_user_id(workspace) if target.nil? || target == 'me'
+        return target if target.match?(/\A[UW][A-Z0-9]+\z/)
+
+        Services::UserLookup.new(
+          cache_store: cache_store,
+          workspace: workspace,
+          api_client: api_client,
+          on_debug: ->(msg) { output.debug(msg) }
+        ).find_id_by_name(target.delete_prefix('@')) ||
+          (raise ApiError, "Could not resolve user: #{target}")
+      end
+
+      def self_user_id(workspace)
+        cached = cache_store.get_meta(workspace.name, 'self_user_id')
+        return cached if cached
+
+        user_id = Api::Client.new(api_client, workspace).auth_test['user_id']
+        cache_store.set_meta(workspace.name, 'self_user_id', user_id) if user_id
+        user_id
+      end
+    end
+  end
+end