anima-core 1.3.0 → 1.5.0

data/lib/tui/screens/chat.rb

@@ -20,30 +20,23 @@ module TUI
     class Chat
       include Formatting
 
-      MIN_INPUT_HEIGHT = 3
       PRINTABLE_CHAR = /\A[[:print:]]\z/
 
       ROLE_USER = "user"
       ROLE_ASSISTANT = "assistant"
 
-      SCROLL_STEP = 1
-      MOUSE_SCROLL_STEP = 2
-
       TOOL_ICON = "\u{1F527}"
       CHECKMARK = "\u2713"
 
-      # Viewport virtualization tuning
-      VIEWPORT_BACK_BUFFER = 3    # entries before scroll target for upward scroll margin
-      VIEWPORT_OVERFLOW_MULTIPLIER = 2 # build this many viewports worth of lines
-      VIEWPORT_BOTTOM_THRESHOLD = 10   # entries from end before we include all trailing
-
       # Background-highlighted styles for conversation roles.
       # Dark tinted backgrounds make user/assistant messages easy to scan.
-      # 22 = dark green (#005f00), 17 = dark navy (#00005f) in 256-color.
-      ROLE_STYLES = {
-        "user" => {fg: "white", bg: 22, modifiers: [:bold]},
-        "assistant" => {fg: "white", bg: 17, modifiers: [:bold]}
-      }.freeze
+      # Colors configured via [theme] user_message_bg / assistant_message_bg.
+      def self.role_styles
+        {
+          "user" => {fg: Settings.theme_color_text, bg: Settings.theme_user_message_bg, modifiers: [:bold]},
+          "assistant" => {fg: Settings.theme_color_text, bg: Settings.theme_assistant_message_bg, modifiers: [:bold]}
+        }
+      end
 
       # Intentionally duplicated from Session::VIEW_MODES to keep the TUI
       # independent of Rails. Must stay in sync when adding new modes.
@@ -268,8 +261,8 @@ module TUI
       # @return [String]
       def spinner_label
         case @session_state
-        when "llm_generating" then "Thinking..."
-        when "tool_executing" then "Executing..."
+        when "awaiting" then "Thinking..."
+        when "executing" then "Executing..."
         when "interrupting" then "Stopping..."
         else "Working..."
         end
@@ -282,9 +275,9 @@ module TUI
       # @return [String]
       def spinner_color
         case @session_state
-        when "llm_generating", "tool_executing" then "green"
-        when "interrupting" then "red"
-        else "dark_gray"
+        when "awaiting", "executing" then Settings.theme_color_success
+        when "interrupting" then Settings.theme_color_error
+        else Settings.theme_color_muted
         end
       end
 
@@ -322,10 +315,12 @@ module TUI
             handle_goals_updated(msg)
           when "children_updated"
             handle_children_updated(msg)
+          when "subagent_evicted"
+            handle_subagent_evicted(msg)
           when "sessions_list"
             @sessions_list = msg["sessions"]
           when "pending_message_created"
-            @message_store.add_pending(msg["pending_message_id"], msg["content"]) if msg["pending_message_id"]
+            @message_store.add_pending(msg["pending_message_id"], msg) if msg["pending_message_id"]
           when "pending_message_removed"
             @message_store.remove_pending(msg["pending_message_id"]) if msg["pending_message_id"]
           when "authentication_required"
@@ -363,20 +358,20 @@ module TUI
             end
           end
 
-          handle_viewport_evictions(msg)
+          handle_eviction(msg) if msg["action"] == "eviction"
         end
       end
 
-      # Removes messages that left the LLM's context window. Broadcasts
-      # include `evicted_message_ids` when old messages are pushed out of the
-      # viewport by new ones.
+      # Removes messages above the eviction cutoff from the message store.
+      # Triggered by {Events::EvictionCompleted} when Mneme advances the
+      # boundary past an eviction zone.
       #
-      # @param msg [Hash] incoming WebSocket message
-      def handle_viewport_evictions(msg)
-        evicted_ids = msg["evicted_message_ids"]
-        return unless evicted_ids.is_a?(Array) && evicted_ids.any?
+      # @param msg [Hash] incoming WebSocket message with "evict_above_id"
+      def handle_eviction(msg)
+        cutoff = msg["evict_above_id"]
+        return unless cutoff
 
-        @message_store.remove_by_ids(evicted_ids)
+        @message_store.remove_above(cutoff)
       end
 
       # Renders flash messages as colored bars inside the chat frame,
@@ -456,7 +451,7 @@ module TUI
         @session_info[:name] = msg["name"]
       end
 
-      # Updates the active skills list when the analytical brain activates or
+      # Updates the active skills list when Melete activates or
       # deactivates skills. Only applies to the current session.
       def handle_active_skills_updated(msg)
         return unless msg["session_id"] == @session_info[:id]
@@ -464,7 +459,7 @@ module TUI
         @session_info[:active_skills] = msg["active_skills"] || []
       end
 
-      # Updates the active workflow when the analytical brain activates or
+      # Updates the active workflow when Melete activates or
       # deactivates a workflow. Only applies to the current session.
       def handle_active_workflow_updated(msg)
         return unless msg["session_id"] == @session_info[:id]
@@ -472,7 +467,7 @@ module TUI
         @session_info[:active_workflow] = msg["active_workflow"]
       end
 
-      # Updates the goals list when the analytical brain creates or
+      # Updates the goals list when Melete creates or
       # completes goals. Only applies to the current session.
       def handle_goals_updated(msg)
         return unless msg["session_id"] == @session_info[:id]
@@ -488,6 +483,20 @@ module TUI
         @session_info[:children] = msg["children"] || []
       end
 
+      # Removes a sub-agent from the HUD panel when viewport eviction has
+      # taken its last trace past the Mneme boundary. Only applies to the
+      # current session — the brain emits this only on the parent's stream.
+      #
+      # @param msg [Hash] ActionCable payload with "session_id" and "child_id" keys
+      def handle_subagent_evicted(msg)
+        return unless msg["session_id"] == @session_info[:id]
+
+        child_id = msg["child_id"]
+        return unless child_id
+
+        @session_info[:children] = @session_info[:children]&.reject { |child| child["id"] == child_id }
+      end
+
       # Handles explicit session state transitions from the server.
       # Drives the braille spinner animation. Only processes broadcasts
       # matching the current session.
@@ -510,14 +519,14 @@ module TUI
         child_id = msg["child_id"]
         return unless child_id
 
-        child = @session_info[:children]&.find { |c| c["id"] == child_id }
-        child["session_state"] = msg["state"] if child
+        entry = @session_info[:children]&.find { |child| child["id"] == child_id }
+        entry["session_state"] = msg["state"] if entry
       end
 
       # Updates the session state and synchronizes the spinner.
       #
-      # @param state [String] one of "idle", "llm_generating",
-      #   "tool_executing", "interrupting"
+      # @param state [String] one of "idle", "awaiting",
+      #   "executing", "interrupting"
       def update_session_state(state)
         @session_state = state
         @spinner.state = state
@@ -598,7 +607,7 @@ module TUI
 
         # Phase 5: Paragraph widget + wrapped line count
         base_widget = @perf_logger.measure(:paragraph) {
-          tui.paragraph(text: lines, wrap: true, style: tui.style(fg: "white"))
+          tui.paragraph(text: lines, wrap: true, style: tui.style(fg: Settings.theme_color_text))
         }
         wrapped_height = @perf_logger.measure(:line_count) {
           cached_viewport_line_count(base_widget, inner_width, version)
@@ -633,9 +642,9 @@ module TUI
             content_length: @max_scroll,
             position: @scroll_offset,
             orientation: :vertical_right,
-            thumb_style: {fg: "cyan"},
+            thumb_style: {fg: Settings.theme_scrollbar_thumb},
             track_symbol: "\u2502",
-            track_style: {fg: "dark_gray"}
+            track_style: {fg: Settings.theme_scrollbar_track}
           )
           frame.render_widget(scrollbar, area)
         end
@@ -678,15 +687,15 @@ module TUI
           [spinner_line(tui)]
         elsif @session_loading
           [tui.line(spans: [
-            tui.span(content: "Loading session\u2026", style: tui.style(fg: "yellow"))
+            tui.span(content: "Loading session\u2026", style: tui.style(fg: Settings.theme_color_warning))
           ])]
         else
           [tui.line(spans: [
-            tui.span(content: "Type a message to start chatting.", style: tui.style(fg: "dark_gray"))
+            tui.span(content: "Type a message to start chatting.", style: tui.style(fg: Settings.theme_color_muted))
           ])]
         end
 
-        widget = tui.paragraph(text: lines, wrap: true, style: tui.style(fg: "white"))
+        widget = tui.paragraph(text: lines, wrap: true, style: tui.style(fg: Settings.theme_color_text))
           .with(scroll: [0, 0], block: tui.block(**chat_block_config))
         frame.render_widget(widget, area)
         @max_scroll = 0
@@ -729,12 +738,12 @@ module TUI
         entry_count = entries.size
 
         # Start a few entries before the scroll target for upward buffer
-        buf_first = [first_visible_est - VIEWPORT_BACK_BUFFER, 0].max
+        buf_first = [first_visible_est - Settings.chat_viewport_back_buffer, 0].max
 
         # Build forward until we've accumulated enough lines to fill the
         # viewport with margin. Pre-wrap count is a lower bound on visual
         # height (wrapping only adds lines), so 2x guarantees coverage.
-        target = @visible_height * VIEWPORT_OVERFLOW_MULTIPLIER
+        target = @visible_height * Settings.chat_viewport_overflow_multiplier
         lines = []
         pre_wrap_count = 0
         buf_last = buf_first
@@ -748,7 +757,7 @@ module TUI
           # the bottom. Near the bottom, always include trailing entries
           # so the viewport covers the actual end of content — otherwise
           # the last entries become unreachable.
-          break if pre_wrap_count >= target && entry_count - idx > VIEWPORT_BOTTOM_THRESHOLD
+          break if pre_wrap_count >= target && entry_count - idx > Settings.chat_viewport_bottom_threshold
         end
 
         @perf_logger.info(
@@ -815,6 +824,10 @@ module TUI
           lines = estimate_text_height(text, effective_width)
           lines += 1 # header/label line
           lines += 1 unless entry[:message_type] == "tool_call" # separator
+          if data["tools"].is_a?(Array) && data["tools"].any?
+            lines += 2 # blank line + "## Tools (N)" header
+            lines += estimate_text_height(tools_toon(data), effective_width)
+          end
           lines
         when :message
           lines = estimate_text_height(entry[:content].to_s, effective_width)
@@ -853,7 +866,7 @@ module TUI
           title: "Chat",
           borders: [:all],
           border_type: :rounded,
-          border_style: @chat_focused ? {fg: "yellow"} : {fg: "cyan"}
+          border_style: @chat_focused ? {fg: Settings.theme_border_focused} : {fg: Settings.theme_color_info}
         }
         if @chat_focused
           config[:titles] = [
@@ -873,7 +886,7 @@ module TUI
         responses = counter[:responses]
         complete = calls == responses
         label = "#{TOOL_ICON} Tools: #{calls}/#{responses}#{" #{CHECKMARK}" if complete}"
-        color = complete ? "green" : "yellow"
+        color = complete ? Settings.theme_color_success : Settings.theme_color_warning
         [
           tui.line(spans: [tui.span(content: label, style: tui.style(fg: color))]),
           tui.line(spans: [tui.span(content: "")])
@@ -900,8 +913,14 @@ module TUI
           render_system_entry(tui, data)
         when "system_prompt"
           render_system_prompt_entry(tui, data)
+        when "pending_subagent"
+          render_pending_subagent_entry(tui, data)
+        when "pending_melete"
+          render_pending_melete_entry(tui, data)
+        when "pending_mneme"
+          render_pending_mneme_entry(tui, data)
         else
-          [tui.line(spans: [tui.span(content: data["content"].to_s, style: tui.style(fg: "white"))])]
+          [tui.line(spans: [tui.span(content: data["content"].to_s, style: tui.style(fg: Settings.theme_color_text))])]
         end
 
         # Tool calls and their responses are visually one unit — no separator
@@ -935,9 +954,9 @@ module TUI
         label = role_label(role)
 
         if pending
-          style = tui.style(fg: "gray")
+          style = tui.style(fg: Settings.theme_color_muted)
         else
-          role_cfg = ROLE_STYLES.fetch(role, {fg: "white"})
+          role_cfg = self.class.role_styles.fetch(role, {fg: Settings.theme_color_text})
           style = tui.style(**role_cfg)
         end
 
@@ -949,7 +968,7 @@ module TUI
 
         first_spans = if tokens && !pending
           tok_style = {fg: token_count_color(tokens)}
-          role_bg = ROLE_STYLES.dig(role, :bg)
+          role_bg = self.class.role_styles.dig(role, :bg)
           tok_style[:bg] = role_bg if role_bg
           [
             tui.span(content: ts_prefix, style: style),
@@ -962,7 +981,7 @@ module TUI
         end
 
         lines = [tui.line(spans: first_spans)]
-        content_lines.drop(1).each { |line| lines << tui.line(spans: [tui.span(content: line, style: style)]) }
+        content_lines.drop(1).each { |line| lines << tui.line(spans: [tui.span(content: preserve_indentation(line), style: style)]) }
         lines
       end
 
@@ -973,11 +992,63 @@ module TUI
       def render_system_entry(tui, data)
         ts = data["timestamp"]
         header = ts ? "[#{format_ns_timestamp(ts)}] [system]" : "[system]"
-        style = tui.style(fg: "white")
+        style = tui.style(fg: Settings.theme_color_text)
 
         content_lines = data["content"].to_s.split("\n", -1)
         lines = [tui.line(spans: [tui.span(content: "#{header} #{content_lines.first}", style: style)])]
-        content_lines.drop(1).each { |line| lines << tui.line(spans: [tui.span(content: "  #{line}", style: style)]) }
+        content_lines.drop(1).each { |line| lines << tui.line(spans: [tui.span(content: preserve_indentation("  #{line}"), style: style)]) }
+        lines
+      end
+
+      # Renders a pending sub-agent delivery — a sub-agent's reply that
+      # landed on the parent's mailbox and is queued for promotion. Shows
+      # a +[from <nickname>]+ badge in the muted color so it reads as
+      # in-flight, distinct from a real conversation message.
+      # @param tui [RatatuiRuby] TUI rendering API
+      # @param data [Hash] structured data with "source", "content"
+      # @return [Array<RatatuiRuby::Widgets::Line>]
+      def render_pending_subagent_entry(tui, data)
+        render_pending_badge_entry(tui, data, badge: "from #{data["source"]}")
+      end
+
+      # Renders a pending Mneme recall — a memory Mneme will inject as a
+      # phantom tool pair on the next active drain. Visible from verbose
+      # so the user can see what context is about to enter the LLM turn.
+      # @param tui [RatatuiRuby] TUI rendering API
+      # @param data [Hash] structured data with "content"
+      # @return [Array<RatatuiRuby::Widgets::Line>]
+      def render_pending_mneme_entry(tui, data)
+        render_pending_badge_entry(tui, data, badge: "Mneme recall")
+      end
+
+      # Renders a pending Melete activation (skill / workflow / goal).
+      # Badge label includes the activation kind and source name, matching
+      # how Melete narrates its own choices in the transcript.
+      # @param tui [RatatuiRuby] TUI rendering API
+      # @param data [Hash] structured data with "kind", "source", "content"
+      # @return [Array<RatatuiRuby::Widgets::Line>]
+      def render_pending_melete_entry(tui, data)
+        render_pending_badge_entry(tui, data, badge: "Melete #{data["kind"]}: #{data["source"]}")
+      end
+
+      # Shared rendering for badge-prefixed pending entries. Header reads
+      # +[<badge>]+ on the first line; body content (when present)
+      # follows on indented continuation lines. Everything renders in the
+      # muted theme color so the eye groups the in-flight pipeline as
+      # distinct from real messages.
+      # @return [Array<RatatuiRuby::Widgets::Line>]
+      def render_pending_badge_entry(tui, data, badge:)
+        style = tui.style(fg: Settings.theme_color_muted)
+        header = "[#{badge}]"
+        first_content = data["content"].to_s
+
+        if first_content.empty?
+          return [tui.line(spans: [tui.span(content: header, style: style)])]
+        end
+
+        content_lines = first_content.split("\n", -1)
+        lines = [tui.line(spans: [tui.span(content: "#{header} #{content_lines.first}", style: style)])]
+        content_lines.drop(1).each { |line| lines << tui.line(spans: [tui.span(content: preserve_indentation("  #{line}"), style: style)]) }
         lines
       end
 
@@ -989,9 +1060,9 @@ module TUI
       # @return [Array<RatatuiRuby::Widgets::Line>]
       def render_system_prompt_entry(tui, data)
         tokens = data["tokens"]
-        bold_style = tui.style(fg: "magenta", modifiers: [:bold])
-        style = tui.style(fg: "magenta")
-        tool_style = tui.style(fg: "cyan")
+        bold_style = tui.style(fg: Settings.theme_color_accent, modifiers: [:bold])
+        style = tui.style(fg: Settings.theme_color_accent)
+        tool_style = tui.style(fg: Settings.theme_color_info)
 
         header_spans = [tui.span(content: "[SYSTEM] ", style: bold_style)]
         if tokens
@@ -1001,14 +1072,14 @@ module TUI
 
         lines = [tui.line(spans: header_spans)]
         data["content"].to_s.split("\n").each do |line|
-          lines << tui.line(spans: [tui.span(content: "  #{line}", style: style)])
+          lines << tui.line(spans: [tui.span(content: preserve_indentation("  #{line}"), style: style)])
         end
 
         if data["tools"].is_a?(Array) && data["tools"].any?
           lines << tui.line(spans: [tui.span(content: "", style: style)])
-          lines << tui.line(spans: [tui.span(content: "\u00a0\u00a0## Tools (#{data["tools"].size})", style: bold_style)])
+          lines << tui.line(spans: [tui.span(content: preserve_indentation("  ## Tools (#{data["tools"].size})"), style: bold_style)])
           tools_toon(data).split("\n").each do |line|
-            lines << tui.line(spans: [tui.span(content: line, style: tool_style)])
+            lines << tui.line(spans: [tui.span(content: preserve_indentation(line), style: tool_style)])
           end
         end
 
@@ -1017,18 +1088,17 @@ module TUI
 
       # Converts tool schemas to TOON format for display. Caches the result
       # on the data hash so the conversion runs once per broadcast, not per
-      # frame. Uses non-breaking spaces for indentation because ratatui's
-      # Paragraph widget with wrap:true trims regular leading spaces.
+      # frame. NBSP substitution is applied at the span level via
+      # preserve_indentation, not here.
       # @param data [Hash] entry data containing "tools" array
       # @return [String] TOON-formatted tool schemas
       def tools_toon(data)
         data["tools_toon"] ||= Toon.encode(data["tools"])
-          .gsub(/^( +)/) { "\u00a0" * _1.length }
       end
 
       def build_chat_message_lines(tui, msg)
         role = msg[:role]
-        role_cfg = ROLE_STYLES.fetch(role, {fg: "white"})
+        role_cfg = self.class.role_styles.fetch(role, {fg: Settings.theme_color_text})
         role_style = tui.style(**role_cfg)
 
         label = role_label(role)
@@ -1036,14 +1106,14 @@ module TUI
 
         lines = [tui.line(spans: [
           tui.span(content: "#{label}: ", style: role_style),
-          tui.span(content: content_lines.first.to_s)
+          tui.span(content: preserve_indentation(content_lines.first.to_s))
         ])]
-        content_lines.drop(1).each { |text| lines << tui.line(spans: [tui.span(content: text)]) }
+        content_lines.drop(1).each { |text| lines << tui.line(spans: [tui.span(content: preserve_indentation(text))]) }
         lines << tui.line(spans: [tui.span(content: "")])
       end
 
       # Dynamically calculates input area height based on wrapped content.
-      # Clamped between MIN_INPUT_HEIGHT and 50% of available height.
+      # Clamped between Settings.chat_min_input_height and 50% of available height.
       def calculate_input_height(_tui, area_width, area_height)
         inner_width = [area_width - 2, 1].max
 
@@ -1052,8 +1122,8 @@ module TUI
         }
         desired = content_height + 2 # top + bottom border
 
-        max_height = [area_height / 2, MIN_INPUT_HEIGHT].max
-        desired.clamp(MIN_INPUT_HEIGHT, max_height)
+        max_height = [area_height / 2, Settings.chat_min_input_height].max
+        desired.clamp(Settings.chat_min_input_height, max_height)
       end
 
       def render_input(frame, area, tui)
@@ -1093,15 +1163,15 @@ module TUI
 
       def input_styles(tui, disabled)
         border_color = if disabled || @chat_focused
-          "dark_gray"
+          Settings.theme_border_input_disconnected
         elsif @session_loading
-          "yellow"
+          Settings.theme_border_input_connecting
         else
-          "green"
+          Settings.theme_border_input_connected
         end
 
         {
-          text: disabled ? tui.style(fg: "dark_gray") : tui.style(fg: "white"),
+          text: disabled ? tui.style(fg: Settings.theme_color_muted) : tui.style(fg: Settings.theme_color_text),
           border: {fg: border_color}
         }
       end
@@ -1263,10 +1333,10 @@ module TUI
       # @return [Boolean] true if the event was handled
       def handle_chat_focused_event(event)
         if event.up?
-          scroll_up(SCROLL_STEP)
+          scroll_up(Settings.chat_scroll_step)
           true
         elsif event.down?
-          scroll_down(SCROLL_STEP)
+          scroll_down(Settings.chat_scroll_step)
           true
         elsif event.home?
           scroll_up(@max_scroll)
@@ -1351,9 +1421,9 @@ module TUI
       # @return [true] always redraws after scrolling
       def handle_scroll_key(event)
         if event.up?
-          scroll_up(SCROLL_STEP)
+          scroll_up(Settings.chat_scroll_step)
         elsif event.down?
-          scroll_down(SCROLL_STEP)
+          scroll_down(Settings.chat_scroll_step)
         elsif event.page_up?
           scroll_up(@visible_height)
         elsif event.page_down?
@@ -1366,10 +1436,10 @@ module TUI
       # @return [Boolean] true if the event was a scroll wheel event
       def handle_mouse_event(event)
         if event.scroll_up?
-          scroll_up(MOUSE_SCROLL_STEP)
+          scroll_up(Settings.chat_mouse_scroll_step)
           true
         elsif event.scroll_down?
-          scroll_down(MOUSE_SCROLL_STEP)
+          scroll_down(Settings.chat_mouse_scroll_step)
           true
         else
           false

data/lib/tui/settings.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "toml-rb"
+
+module TUI
+  # TUI-specific configuration backed by +~/.anima/tui.toml+.
+  #
+  # Zero Rails dependency — the TUI is a standalone client process.
+  #
+  # Accessors are generated automatically from the template TOML file.
+  # Convention: method name = +section_key+ (e.g. +[hud] min_width+ →
+  # +hud_min_width+). To add a setting, add the key to +tui.toml+ — the
+  # accessor appears automatically.
+  #
+  # Settings are loaded once at startup. Restart the TUI to pick up
+  # changes — it's a thin client, the brain won't notice.
+  #
+  # @example Reading a setting
+  #   TUI::Settings.connection_default_host  #=> "localhost:42134"
+  #   TUI::Settings.hud_min_width            #=> 24
+  #
+  # @see Anima::Installer#create_tui_config creates the config file
+  module Settings
+    DEFAULT_PATH = File.expand_path("~/.anima/tui.toml")
+    TEMPLATE_PATH = File.expand_path("../../../templates/tui.toml", __FILE__)
+    TEMPLATE = TomlRB.load_file(TEMPLATE_PATH)
+
+    class MissingConfigError < StandardError; end
+    class MissingSettingError < StandardError; end
+
+    @config_path = nil
+
+    class << self
+      TEMPLATE.each do |section, keys|
+        keys.each_key { |key| attr_reader :"#{section}_#{key}" }
+      end
+
+      # Override config file path (for testing).
+      # Triggers a load so the new config takes effect immediately.
+      #
+      # @param path [String, nil] custom path, or +nil+ to restore default
+      def config_path=(path)
+        @config_path = path
+        load! if path
+      end
+
+      # @return [String] active config file path
+      def config_path
+        @config_path || DEFAULT_PATH
+      end
+
+      # Restores template defaults and clears the path override.
+      # Useful in test teardown.
+      def reset!
+        @config_path = nil
+        load_defaults!
+      end
+
+      # Populates ivars from the cached {TEMPLATE} hash without touching disk.
+      # Intended for test suites that want template defaults without paying
+      # the TOML parse cost for every example.
+      def load_defaults!
+        TEMPLATE.each do |section, keys|
+          keys.each { |key, value| instance_variable_set(:"@#{section}_#{key}", value) }
+        end
+      end
+
+      # Parses the config file and populates all setting ivars.
+      #
+      # @raise [MissingConfigError] when tui.toml does not exist
+      # @raise [MissingSettingError] when a template key is missing from config
+      def load!
+        path = config_path
+        unless File.exist?(path)
+          raise MissingConfigError,
+            "TUI config file not found: #{path}. Run `anima install` to create it."
+        end
+
+        parsed = TomlRB.load_file(path)
+        TEMPLATE.each do |section, keys|
+          keys.each_key do |key|
+            value = parsed.dig(section, key)
+            if value.nil?
+              raise MissingSettingError,
+                "[#{section}] #{key} is not set in #{path}. Run `anima update` to add missing settings."
+            end
+            instance_variable_set(:"@#{section}_#{key}", value)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/workflows/definition.rb

@@ -7,10 +7,10 @@ module Workflows
 
   # A workflow parsed from a Markdown definition file.
   # YAML frontmatter holds metadata; the Markdown body contains free-form
-  # instructions that the analytical brain reads and converts into goals.
+  # instructions that Melete reads and converts into goals.
   #
   # Workflows are operational recipes — they describe WHAT to do step by
-  # step. The analytical brain uses judgment to decompose workflow prose
+  # step. Melete uses judgment to decompose workflow prose
   # into tracked goals based on the user's specific context.
   #
   # @example Workflow file format
@@ -25,7 +25,7 @@ module Workflows
     # @return [String] unique workflow identifier used in read_workflow(name: "...")
     attr_reader :name
 
-    # @return [String] description shown to the analytical brain for relevance matching
+    # @return [String] description shown to Melete for relevance matching
     attr_reader :description
 
     # @return [String] workflow content (Markdown body) — free-form instructions

data/lib/workflows/registry.rb

@@ -64,7 +64,7 @@ module Workflows
       @workflows[name]
     end
 
-    # Workflow names and descriptions for inclusion in the analytical brain's context.
+    # Workflow names and descriptions for inclusion in Melete's context.
     #
     # @return [Hash{String => String}] name => description
     def catalog

data/skills/github.md

@@ -0,0 +1,38 @@
+---
+name: github
+description: "GitHub operations — issues, pull requests, releases, CI runs, comments. Activate when an issue or PR number comes up, or when the conversation turns to repo state."
+---
+
+# GitHub
+
+`gh` is installed and authenticated.
+
+## Sub-issues — REST only
+
+Not in top-level `gh` commands. Use the issue's *global ID* (not its number):
+
+```bash
+REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner)
+ISSUE_ID=$(gh api repos/$REPO/issues/42 --jq '.id')
+
+# add
+gh api repos/$REPO/issues/36/sub_issues -X POST -F sub_issue_id=$ISSUE_ID
+
+# list
+gh api repos/$REPO/issues/36/sub_issues
+
+# reorder (move one to sit after another)
+gh api repos/$REPO/issues/36/sub_issues/priority -X PATCH \
+  -F sub_issue_id=$ISSUE_ID -F after_id=$AFTER_ID
+```
+
+## Reading JSON
+
+`gh` JSON output is token-expensive. Pipe through `toon` — a lossless LLM-optimized format that round-trips back to JSON:
+
+```bash
+gh pr view 459 --json title,body,reviewDecision | toon
+gh api repos/$REPO/pulls/459/comments | toon
+```
+
+Skip `toon` when the output is going into further tooling that needs raw JSON (jq, scripts).