rosett-ai 1.3.3 → 1.5.10

data/lib/rosett_ai/thor/tasks/build.rb

@@ -22,6 +22,10 @@ module RosettAi
         :stage_timings, :completed_stages,
         :failed_stage, :failure_reason, :summary_printed
       ) do
+        # Create a new build context with a unique ID and log file.
+        #
+        # @param log_dir [Pathname] directory for build log files
+        # @return [BuildContext]
         def self.create(log_dir)
           id = SecureRandom.uuid
           log_path = log_dir.join("build-#{id}.log")
@@ -60,6 +64,7 @@ module RosettAi
 
         default_task :create
 
+        # @return [String] Target installation directory for packages.
         INSTALL_DIR = '/opt/rosett-ai'
 
         # Files/directories excluded when syncing app source into the staging tree
@@ -68,9 +73,12 @@ module RosettAi
           '.git', '.gitignore',
           # Bundler / gem build artifacts
           '.bundle', '.binstubs', 'vendor/bundle', '*.gem',
-          'Gemfile.dev', 'Gemfile.dev.lock', 'Gemfile.integration',
+          'Gemfile.dev', 'Gemfile.dev.lock',
+          'Gemfile.integration', 'Gemfile.integration.lock',
           # CI/CD
           '.gitlab-ci*',
+          # CI artifacts — never ship test/lint output
+          'rspec-report.xml', 'rubocop-report.json',
           # Build & packaging
           'coverage', 'tmp', 'pkg', 'spec', 'test', 'packaging',
           # Dev tool configs
@@ -79,8 +87,24 @@ module RosettAi
           '.overcommit.yml', '.git-hooks',
           '.mdlrc', '.mdl_style.rb', '.yamllint', '.yardopts',
           '.project', '.rosett-ai',
+          # Dev-only documentation (not needed at runtime)
+          'doc/api', 'doc/reference', 'doc/context', 'doc/issues',
+          'doc/decisions', 'doc/changes', 'doc/design',
+          # Security advisories — internal, never ship publicly
+          'doc/security',
+          # Design docs — carry internal WP refs, not runtime-required
+          'conf/design',
+          # Behaviour rules — user-authored, must never ship in packages (sec_001/rule_073)
+          'conf/behaviour',
+          # Peer review configs (dev-only)
+          'conf/review',
           # AI assistant state — never ship in package
           '.claude', 'doc/claude-sessions',
+          # AI provenance file — dev-only provenance tracking, not runtime-required
+          '.ai-provenance.yml',
+          # Internal audit, operations, signing, and rule-audit documents
+          'doc/audits', 'doc/operations', 'doc/signing',
+          'doc/rules-audit-*.md',
           'cliff.toml', 'kitchen.yml', 'Rakefile'
         ].freeze
 
@@ -89,7 +113,7 @@ module RosettAi
           :validate, :clean, :prepare, :compile_ruby,
           :sync_app, :install_gems, :clean_build_artifacts,
           :install_wrapper,
-          :install_config, :install_man, :install_build_info, :package
+          :install_config, :install_systemd, :install_man, :install_build_info, :rewrite_shebangs, :package
         ].freeze
 
         # Bundler/RubyGems environment variables that must be stripped
@@ -162,6 +186,9 @@ module RosettAi
                       default: 'core',
                       desc: 'Package variant (core, gtk4, qt6)'
 
+        # Build a .deb package for the specified variant.
+        #
+        # @return [void]
         def create
           unless RosettAi.context.rai_internal?
             raise ::Thor::Error,
@@ -181,8 +208,10 @@ module RosettAi
           run_stage(:clean_build_artifacts) { clean_build_artifacts! }
           run_stage(:install_wrapper) { install_wrapper! }
           run_stage(:install_config) { install_default_config! }
+          run_stage(:install_systemd) { install_systemd_unit! }
           run_stage(:install_man) { install_man_pages! }
           run_stage(:install_build_info) { install_build_info! }
+          run_stage(:rewrite_shebangs) { rewrite_shebangs! }
           run_stage(:package) { build_package! }
 
           print_build_summary(:success)
@@ -295,7 +324,7 @@ module RosettAi
         end
 
         def check_ronn_available!
-          ronn_source = project_root.join('doc', 'man', 'rai.1.ronn')
+          ronn_source = project_root.join('doc', 'man', 'raictl.1.ronn')
           return unless ronn_source.exist?
 
           begin
@@ -415,13 +444,24 @@ module RosettAi
         # -- gem installation --------------------------------------------------
 
         def install_gems!
-          spinner = build_spinner('Installing gems (deployment mode)...')
+          spinner = build_spinner('Installing gems into embedded gem home...')
+          ruby_abi = query_embedded_ruby('RbConfig::CONFIG["ruby_version"]')
+          gem_home = staging_embedded.join('lib', 'ruby', 'gems', ruby_abi)
+          FileUtils.mkdir_p(gem_home)
           embedded_bundle = staging_embedded.join('bin', 'bundle').to_s
 
-          env = embedded_env
+          # Install runtime deps directly into the embedded Ruby's own gem home.
+          # The embedded ruby finds them by default (via GEM_HOME) with no wrapper
+          # env vars or bundler/setup at runtime — proving genuine self-containment.
+          env = clean_env.merge(
+            'PATH' => "#{staging_embedded.join('bin')}:#{HERMETIC_SYSTEM_PATH}",
+            'BUNDLE_GEMFILE' => staging_app.join('Gemfile').to_s,
+            'GEM_HOME' => gem_home.to_s,
+            'GEM_PATH' => gem_home.to_s,
+            'LD_LIBRARY_PATH' => staging_embedded.join('lib').to_s
+          )
+
           cmds = [
-            [env, embedded_bundle, 'config', 'set', '--local', 'deployment', 'true'],
-            [env, embedded_bundle, 'config', 'set', '--local', 'path', 'vendor/bundle'],
             [env, embedded_bundle, 'config', 'set', '--local', 'without', 'development test build desktop engines'],
             [env, embedded_bundle, 'config', 'set', '--local', 'jobs', jobs_count.to_s],
             [env, embedded_bundle, 'install']
@@ -433,8 +473,8 @@ module RosettAi
             spinner.error(Rainbow(' failed').red)
             log_bundle_debug(env, embedded_bundle)
             abort_build(<<~MSG.chomp)
-              Gem installation failed.
-                The embedded Ruby bundler could not resolve or install gems.
+              Gem installation into embedded gem home failed.
+                The embedded Ruby bundler could not install gems into #{gem_home}.
                 This usually means Bundler environment variables from the parent
                 process leaked into the build. Check the build log for details.
             MSG
@@ -463,8 +503,8 @@ module RosettAi
         end
 
         def collect_build_artifacts
-          Dir.glob(staging_app.join('vendor', 'bundle', '**', '{gem_make.out,mkmf.log}')) +
-            Dir.glob(staging_app.join('vendor', 'bundle', '**', 'ext', '**', 'Makefile'))
+          Dir.glob(staging_embedded.join('lib', 'ruby', 'gems', '**', '{gem_make.out,mkmf.log}')) +
+            Dir.glob(staging_embedded.join('lib', 'ruby', 'gems', '**', 'ext', '**', 'Makefile'))
         end
 
         def remove_artifact(path)
@@ -494,15 +534,6 @@ module RosettAi
         # 1. Unsets all Bundler/RubyGems vars inherited from `bundle exec`
         # 2. Sets PATH to prefer the embedded Ruby
         # 3. Points BUNDLE_GEMFILE at the staging app's Gemfile
-        def embedded_env
-          env = clean_env.merge(
-            'PATH' => "#{staging_embedded.join('bin')}:#{HERMETIC_SYSTEM_PATH}",
-            'BUNDLE_GEMFILE' => staging_app.join('Gemfile').to_s
-          )
-          log_to_file("embedded_env: #{env.inspect}")
-          env
-        end
-
         # Strips all Bundler/RubyGems variables. When passed to system(),
         # nil values cause the variable to be unset in the child process.
         def clean_env
@@ -560,10 +591,25 @@ module RosettAi
           log_verbose("Installed conffile to #{etc_dir.join('settings.json')}")
         end
 
+        # -- systemd -----------------------------------------------------------
+
+        def install_systemd_unit!
+          systemd_src = packaging_dir.join('lib', 'systemd')
+          return log_verbose('No systemd unit source found — skipping') unless systemd_src.directory?
+
+          systemd_dest = staging_install.join('lib', 'systemd')
+          FileUtils.mkdir_p(systemd_dest)
+
+          Dir.glob(systemd_src.join('*').to_s).each do |src_path|
+            FileUtils.cp_r(src_path, systemd_dest)
+            log_verbose("Installed #{File.basename(src_path)} to #{systemd_dest}")
+          end
+        end
+
         # -- man pages ---------------------------------------------------------
 
         def install_man_pages!
-          ronn_source = project_root.join('doc', 'man', 'rai.1.ronn')
+          ronn_source = project_root.join('doc', 'man', 'raictl.1.ronn')
           return log_verbose('No man page source found — skipping') unless ronn_source.exist?
 
           man_dir = staging_dir.join('usr', 'share', 'man', 'man1')
@@ -590,6 +636,39 @@ module RosettAi
           log_verbose("Installed build info to #{dest}")
         end
 
+        # -- shebang rewrite ---------------------------------------------------
+
+        # ruby-build compiles with the staging prefix as --prefix, so scripts
+        # in embedded/bin/ (gem, bundle, rake, irb, …) carry the build-time
+        # staging path in their shebang. Rewrite all ruby-shebang scripts to
+        # the runtime path AFTER gem installation (which still needs the
+        # staging shebang to run bundle) and BEFORE packaging.
+        def rewrite_shebangs!
+          spinner = build_spinner('Rewriting embedded bin shebangs...')
+          bin_dir = staging_embedded.join('bin')
+          count = count_shebang_rewrites(bin_dir, '#!/opt/rosett-ai/embedded/bin/ruby')
+          log_verbose("Rewrote #{count} shebang(s) in #{bin_dir}")
+          spinner.success(Rainbow(" done (#{count} scripts)").green)
+        end
+
+        def count_shebang_rewrites(bin_dir, target)
+          return 0 unless bin_dir.directory?
+
+          bin_dir.each_child.count { |path| !path.directory? && rewrite_ruby_shebang!(path, target) }
+        end
+
+        def rewrite_ruby_shebang!(path, target)
+          content = path.binread
+          return unless content.start_with?('#!')
+
+          nl = content.index("\n") || content.length
+          first_line = content[0, nl]
+          return unless first_line.include?('ruby') && first_line.strip != target
+
+          path.binwrite("#{target}#{content[nl..]}")
+          true
+        end
+
         def build_info_content
           <<~INFO
             version=#{RosettAi::VERSION}
@@ -741,8 +820,10 @@ module RosettAi
             install_gems: 'Install gems (deployment)',
             install_wrapper: 'Install wrapper script',
             install_config: 'Install default config',
+            install_systemd: 'Install systemd unit',
             install_man: 'Install man pages',
             install_build_info: 'Install build info',
+            rewrite_shebangs: 'Rewrite embedded bin shebangs',
             package: 'Build .deb with fpm'
           }.fetch(stage, stage.to_s)
         end
@@ -848,6 +929,7 @@ module RosettAi
 
         default_task :create
 
+        # @return [String] Base installation path for engine plugins.
         INSTALL_BASE = '/opt/rosett-ai/embedded/lib/ruby/gems'
 
         desc 'create', 'Build a .deb package for an rosett-ai engine plugin'
@@ -885,6 +967,9 @@ module RosettAi
                       default: 1,
                       desc: 'Package build iteration (release number)'
 
+        # Build a .deb package for an engine plugin.
+        #
+        # @return [void]
         def create
           resolve_engine_dir!
           detect_gemspec!

data/lib/rosett_ai/thor/tasks/compile.rb

@@ -30,6 +30,7 @@ module RosettAi
             --simulate: Dry run with diffs, no file writes
             --vendor: Write compile.lock.yml lockfile
             --engine NAME: Compile for specific engine
+            --scope SCOPE: Compile scope (global/project/auto)
             --strict: Treat warnings as errors
             --locales: Compile locale files to gettext/Qt formats
 
@@ -39,6 +40,8 @@ module RosettAi
 
             raictl compile
             raictl compile --verbose --simulate
+            raictl compile --scope global
+            raictl compile --scope project
             raictl compile --engine generic --strict
             raictl compile --vendor
             raictl compile --locales
@@ -73,11 +76,18 @@ module RosettAi
                       type: :boolean,
                       default: false,
                       desc: 'Treat warnings as errors'
+        method_option :scope,
+                      type: :string,
+                      default: 'auto',
+                      enum: ['global', 'project', 'auto'],
+                      desc: 'Compile scope: global (~/.claude/rules/), project (.claude/rules/), or auto-detect'
         method_option :locales,
                       type: :boolean,
                       default: false,
                       desc: 'Compile locale files to gettext and Qt formats'
 
+        # Generate the compiled output.
+        # @return [void]
         def generate
           if options[:locales]
             compile_locales
@@ -153,8 +163,17 @@ module RosettAi
         end
 
         def detect_compile_scope
-          ctx = RosettAi.context
-          ctx.project? && !ctx.rai_internal? ? :project : :global
+          case options[:scope]
+          when 'global'
+            :global
+          when 'project'
+            raise RosettAi::CompileError, t('compile.scope_project_no_project') unless RosettAi.context.project?
+
+            :project
+          else # 'auto'
+            ctx = RosettAi.context
+            ctx.project? && !ctx.rai_internal? ? :project : :global
+          end
         end
 
         def check_xdg_migration
@@ -236,30 +255,18 @@ module RosettAi
           RosettAi.paths.rules_dir
         end
 
-        # Resolves the target directory for a compiled output based on its
-        # declared scope. Falls back to the pipeline's target_dir when no
-        # scope is declared or the behaviour's scope matches the pipeline's.
+        # Resolves the target directory for a compiled output.
         #
-        # Scope routing:
-        #   global/personal → ~/.claude/rules/ (global rules dir)
-        #   project          → .claude/rules/  (project-local)
-        #   nil              → pipeline default (current behaviour)
-        def resolve_scoped_target_dir(compiler, info)
-          declared_scope = info[:scope]
-          return compiler.target_dir unless declared_scope
-
-          case declared_scope
-          when 'project'
-            if RosettAi.context.project?
-              RosettAi.context.project_root.join('.claude', 'rules')
-            else
-              compiler.target_dir
-            end
-          when 'global', 'personal'
-            RosettAi.paths.rules_dir
-          else
-            compiler.target_dir
-          end
+        # Always returns the pipeline's target_dir to prevent cross-directory
+        # writes. The pipeline scope (global vs project) already determines
+        # the correct output directory. Per-file scope metadata is preserved
+        # in lockfile output but does not affect write location.
+        #
+        # Previously, per-file scope: global/personal routed to
+        # ~/.claude/rules/ even during project-scope compilation, causing
+        # Claude Code to load duplicate rules from both directories.
+        def resolve_scoped_target_dir(compiler, _info)
+          compiler.target_dir
         end
 
         def compile_locales
@@ -296,10 +303,17 @@ module RosettAi
 
           compiled.each do |filename, info|
             target_dir = resolve_scoped_target_dir(compiler, info)
-            target_path = target_dir.join(filename)
             content = info[:content]
             new_checksum = compiler.checksum(content)
 
+            if deduplicate_against_global?(compiler, target_dir, filename, new_checksum)
+              cleanup_stale_project_copy(target_dir, filename) unless options[:simulate]
+              results[:skipped] << filename
+              log_verbose(t('compile.deduplicated_detail', filename: filename))
+              next
+            end
+
+            target_path = target_dir.join(filename)
             ctx = CompileFileContext.new(
               target_path: target_path, content: content, checksum: new_checksum, filename: filename
             )
@@ -313,6 +327,32 @@ module RosettAi
           results
         end
 
+        # Checks whether a file should be deduplicated against the global
+        # rules directory. In project scope, if a compiled file is identical
+        # to its global counterpart in ~/.claude/rules/, writing it to the
+        # project .claude/rules/ would cause Claude Code to load it twice.
+        #
+        # @return [Boolean] true if the file should be skipped
+        def deduplicate_against_global?(compiler, target_dir, filename, checksum)
+          return false unless compiler.scope == :project
+
+          global_dir = RosettAi.paths.rules_dir
+          return false if target_dir.to_s == global_dir.to_s
+
+          global_file = global_dir.join(filename)
+          return false unless global_file.exist?
+
+          global_checksum = compiler.checksum(File.read(global_file, encoding: 'utf-8'))
+          checksum == global_checksum
+        end
+
+        # Removes a stale project-scope copy that was previously compiled
+        # but is now deduplicated against the global version.
+        def cleanup_stale_project_copy(target_dir, filename)
+          stale_path = target_dir.join(filename)
+          File.delete(stale_path) if stale_path.exist?
+        end
+
         def handle_simulate(compiler, ctx, results)
           if File.exist?(ctx.target_path)
             diff_output = compiler.diff(ctx.target_path, ctx.content)
@@ -366,7 +406,7 @@ module RosettAi
         def remove_orphans(compiler, compiled)
           # Guard: when compile produced no output (e.g. empty project conf/),
           # every managed file in target_dir would appear orphaned. Removing
-          # them would silently destroy all compiled rules. See WP#712.
+          # them would silently destroy all compiled rules.
           return if compiled.empty?
 
           orphans = compiler.orphaned_files(compiled.keys)
@@ -389,11 +429,15 @@ module RosettAi
         end
 
         def print_summary(results)
-          rows = []
-          rows << [t('compile.created'), results[:created].size] unless results[:created].empty?
-          rows << [t('compile.updated'), results[:updated].size] unless results[:updated].empty?
-          rows << [t('compile.unchanged', filename: ''), results[:unchanged].size] unless results[:unchanged].empty?
-
+          label_map = {
+            created: t('compile.created'),
+            updated: t('compile.updated'),
+            unchanged: t('compile.unchanged', filename: ''),
+            skipped: t('compile.deduplicated')
+          }
+          rows = label_map.filter_map do |key, label|
+            [label, results[key].size] unless results[key].empty?
+          end
           return if rows.empty?
 
           puts

data/lib/rosett_ai/thor/tasks/completion.rb

@@ -15,6 +15,7 @@ module RosettAi
       # @author hugo
       # @author claude
       class Completion < ::Thor
+        # @return [Hash] Shell-specific completion installation paths.
         INSTALL_PATHS = {
           'bash' => '/usr/share/bash-completion/completions/rai',
           'zsh' => '/usr/share/zsh/vendor-completions/_rai',
@@ -29,6 +30,8 @@ module RosettAi
 
           Related: completion zsh, completion fish, completion install
         LONGDESC
+        # Generate bash shell completion script.
+        # @return [void]
         def bash
           output_completion('bash')
         end
@@ -41,6 +44,8 @@ module RosettAi
 
           Related: completion bash, completion fish, completion install
         LONGDESC
+        # Generate zsh shell completion script.
+        # @return [void]
         def zsh
           output_completion('zsh')
         end
@@ -53,6 +58,8 @@ module RosettAi
 
           Related: completion bash, completion zsh, completion install
         LONGDESC
+        # Generate fish shell completion script.
+        # @return [void]
         def fish
           output_completion('fish')
         end
@@ -78,6 +85,8 @@ module RosettAi
         LONGDESC
         method_option :shell, type: :string, default: nil,
                               desc: 'Shell to install for (auto-detected from $SHELL)'
+        # Install the component.
+        # @return [void]
         def install
           shell = detect_shell
           generator = RosettAi::Completion::Generator.new

data/lib/rosett_ai/thor/tasks/comply.rb

@@ -46,6 +46,8 @@ module RosettAi
                                 desc: 'Run SPDX header checks only'
         method_option :format, type: :string, enum: ['table', 'json'], default: 'table',
                                desc: 'Output format'
+        # Run the check and return results.
+        # @return [Hash]
         def check
           checks = selected_checks
           results = RosettAi::Comply::Runner.new(

data/lib/rosett_ai/thor/tasks/config.rb

@@ -11,7 +11,7 @@ module RosettAi
   module Thor
     module Tasks
       # Thor task for compiling engine configuration YAML to settings JSON.
-      class Config < ::Thor
+      class Config < ::Thor # rubocop:disable Metrics/ClassLength
         default_task :compile
 
         desc 'show SCOPE', 'Display compiled configuration for a scope with secrets masked'
@@ -36,6 +36,10 @@ module RosettAi
         method_option :engine, type: :string, default: nil,
                                desc: 'Engine name (default: configured default)'
 
+        # Display detailed information for the named item.
+        #
+        # @param scope [Object] the scope
+        # @return [void]
         def show(scope)
           scope = RosettAi::TextSanitizer.normalize_nfc(scope)
           compiler = resolve_config_compiler(simulate: true, masking: true)
@@ -58,6 +62,12 @@ module RosettAi
             --simulate: Dry run without writing files
             --scope NAME: Compile only one scope (managed, user, project, local)
             --engine NAME: Compile for specific engine
+            --strict: Replace target entirely — do not preserve uncategorized entries
+
+          The default (non-strict) compile MERGES with the existing target file,
+          preserving any entries not present in the source YAML scopes and emitting
+          a warning for each. Use --strict to restore the old replace-all behaviour.
+          Run `raictl backfill-user-yml` to capture preserved entries into source.
 
           Exit codes: 1 if any scope fails to compile
 
@@ -66,8 +76,9 @@ module RosettAi
             raictl config compile
             raictl config compile --verbose --simulate
             raictl config compile --scope managed --engine claude
+            raictl config compile --strict
 
-          Related commands: raictl config show, rai compile
+          Related commands: raictl config show, raictl backfill-user-yml, rai compile
         LONGDESC
         method_option :verbose, type: :boolean, default: false,
                                 desc: 'Show detailed output'
@@ -77,9 +88,13 @@ module RosettAi
                               desc: 'Compile specific scope only (managed, user, project, local)'
         method_option :engine, type: :string, default: nil,
                                desc: 'Engine name (default: configured default)'
+        method_option :strict, type: :boolean, default: false,
+                               desc: 'Replace target entirely — do not preserve uncategorized entries'
 
+        # Compile the configuration.
+        # @return [void]
         def compile
-          compiler = resolve_config_compiler(simulate: options[:simulate])
+          compiler = resolve_config_compiler(simulate: options[:simulate], strict: options[:strict])
 
           results = if options[:scope]
                       scope_path = find_scope_file(options[:scope], compiler)
@@ -110,7 +125,7 @@ module RosettAi
           options[:engine] || RosettAi.rai_config.default_engine
         end
 
-        def resolve_config_compiler(simulate: false, masking: false)
+        def resolve_config_compiler(simulate: false, masking: false, strict: false)
           engine_name = resolve_engine_name
 
           unless RosettAi::Plugins::Registry.registered?(:engine, engine_name)
@@ -128,7 +143,8 @@ module RosettAi
           end
 
           secret_resolver = masking ? RosettAi::Config::MaskingSecretResolver.new : nil
-          plugin.config_compiler_class.new(simulate: simulate, secret_resolver: secret_resolver)
+          plugin.config_compiler_class.new(simulate: simulate, secret_resolver: secret_resolver,
+                                           strict: strict)
         end
 
         def engine_hint(available, engine_name)

data/lib/rosett_ai/thor/tasks/content.rb

@@ -32,6 +32,8 @@ module RosettAi
         LONGDESC
         method_option :available, type: :boolean, default: false,
                                   desc: 'Show all available packs with tier labels'
+        # List available items.
+        # @return [void]
         def list
           if options[:available]
             list_available
@@ -53,6 +55,10 @@ module RosettAi
 
           Related commands: raictl content list --available, rai license status
         LONGDESC
+        # Install the component.
+        #
+        # @param pack_name [Object] the pack name
+        # @return [void]
         def install(pack_name)
           result = validate_license!
           tier = result[:tier]
@@ -85,6 +91,8 @@ module RosettAi
 
           Related commands: raictl content list, rai license status
         LONGDESC
+        # Update to the latest version.
+        # @return [void]
         def update
           validate_license!
           registry = RosettAi::Content::PackRegistry.new

data/lib/rosett_ai/thor/tasks/dbus.rb

@@ -21,14 +21,19 @@ module RosettAi
       # @author hugo
       # @author claude
       class DBus < ::Thor
+        # @return [Integer] Exit code for successful D-Bus operation.
         EXIT_SUCCESS = 0
+        # @return [Integer] Exit code for D-Bus connection failure.
         EXIT_DBUS_FAILURE = 1
+        # @return [Integer] Exit code for missing D-Bus dependency.
         EXIT_MISSING_DEPENDENCY = 5
 
+        # @return [Array] Environment variables checked for compositor detection.
         ENV_VARS = [
           'SWAYSOCK', 'I3SOCK', 'HYPRLAND_INSTANCE_SIGNATURE', 'DISPLAY', 'WAYLAND_DISPLAY', 'XDG_RUNTIME_DIR', 'XDG_SESSION_TYPE'
         ].freeze
 
+        # @return [Hash] Maps compositor names to focus adapter classes.
         ADAPTER_MAP = {
           sway: 'I3Adapter (i3ipc)',
           i3: 'I3Adapter (i3ipc)',
@@ -54,6 +59,8 @@ module RosettAi
 
           Related commands: raictl dbus start, rai dbus detect
         LONGDESC
+        # Return the current status.
+        # @return [String]
         def status
           require_desktop_gems!
           check_dbus_availability
@@ -90,6 +97,8 @@ module RosettAi
                       default: false,
                       aliases: '-d',
                       desc: 'Run as daemon (background)'
+        # Start the adapter or service.
+        # @return [void]
         def start
           require_desktop_gems!
           check_dbus_availability
@@ -121,6 +130,8 @@ module RosettAi
 
           Related commands: raictl dbus start, rai dbus status
         LONGDESC
+        # Stop the adapter or service.
+        # @return [void]
         def stop
           require_desktop_gems!
           unless service_running?
@@ -145,6 +156,8 @@ module RosettAi
 
           Related commands: raictl dbus status, rai dbus start
         LONGDESC
+        # Detect available engines on the system.
+        # @return [Array<Hash>]
         def detect
           require_desktop_gems!
           compositor = RosettAi::DBus::CompositorDetector.detect

data/lib/rosett_ai/thor/tasks/design.rb

@@ -87,6 +87,8 @@ module RosettAi
 
           Related commands: raictl design show, rai design validate
         LONGDESC
+        # List available items.
+        # @return [void]
         def list
           files = design_files
           if files.empty?

data/lib/rosett_ai/thor/tasks/desktop.rb

@@ -29,6 +29,8 @@ module RosettAi
 
           Related commands: raictl desktop status, rai dbus start
         LONGDESC
+        # Launch the GTK4 desktop application.
+        # @return [void]
         def gtk4
           require_desktop_gems!
           unless RosettAi::Desktop::Gtk4App.available?
@@ -52,6 +54,8 @@ module RosettAi
 
           Related commands: raictl desktop gtk4, rai dbus status
         LONGDESC
+        # Return the current status.
+        # @return [String]
         def status
           require_desktop_gems!
           gtk4_available = RosettAi::Desktop::Gtk4App.available?