rosett-ai 1.3.3 → 1.5.9

data/lib/rosett_ai/ai_config/context_window.rb

@@ -10,8 +10,11 @@ module RosettAi
     # Tracks max tokens, output reserve, and truncation strategy
     # for compilation into engine-native settings.
     class ContextWindow
+      # @return [Array] Supported context truncation strategy names.
       TRUNCATION_STRATEGIES = ['tail', 'head', 'middle'].freeze
+      # @return [Object] Default maximum token budget.
       DEFAULT_MAX_TOKENS = 200_000
+      # @return [Integer] Default token reserve for response generation.
       DEFAULT_RESERVE = 8192
 
       attr_reader :max_tokens, :output_reserve, :truncation_strategy

data/lib/rosett_ai/ai_config/cost_controls.rb

@@ -11,6 +11,7 @@ module RosettAi
     # These preferences guide model selection and are compiled into
     # engine-specific configuration hints.
     class CostControls
+      # @return [Array] Defined tier levels.
       TIERS = ['economy', 'standard', 'premium'].freeze
 
       attr_reader :preferred_tier, :monthly_budget_note

data/lib/rosett_ai/ai_config/fallback_chain.rb

@@ -11,6 +11,7 @@ module RosettAi
     # engines in order. Warns when a fallback would switch from local to
     # remote (network requirement change).
     class FallbackChain
+      # @return [Array] Engine names that run locally without API calls.
       LOCAL_ENGINES = ['ollama', 'gpt_neox'].freeze
 
       attr_reader :engines, :warnings

data/lib/rosett_ai/ai_config/model_router.rb

@@ -14,6 +14,7 @@ module RosettAi
     # @author hugo
     # @author claude
     class ModelRouter
+      # @return [Array] Canonical model tier definitions.
       CANONICAL_TIERS = ['economy', 'standard', 'premium'].freeze
 
       # Default model mappings per engine (used when engine manifest unavailable).

data/lib/rosett_ai/ai_config/validator.rb

@@ -7,9 +7,11 @@ require 'json'
 require 'json_schemer'
 
 module RosettAi
+  # AI model configuration: routing, cost controls, context windows.
   module AiConfig
     # Validates AI tool configuration files against the JSON Schema.
     class Validator
+      # @return [Object] Path to the JSON Schema file used for validation.
       SCHEMA_PATH = File.join(RosettAi.root, 'conf', 'schemas', 'ai_config_schema.json')
 
       # Validates AI config data against the schema.

data/lib/rosett_ai/authorship/attribution_compiler.rb

@@ -15,6 +15,7 @@ module RosettAi
     # @author hugo
     # @author claude
     class AttributionCompiler
+      # @return [Array] YAML keys that hold file path arrays in authorship config.
       FILES_KEYS = ['files', :files].freeze
 
       # @param disclosure_policy [DisclosurePolicy] active disclosure policy

data/lib/rosett_ai/authorship/disclosure_policy.rb

@@ -21,7 +21,9 @@ module RosettAi
     # @author hugo
     # @author claude
     class DisclosurePolicy
+      # @return [Array] Supported level values.
       LEVELS = ['none', 'minimal', 'standard', 'full'].freeze
+      # @return [String] Default log level.
       DEFAULT_LEVEL = 'standard'
 
       attr_reader :level

data/lib/rosett_ai/authorship/review_validator.rb

@@ -4,6 +4,7 @@
 # Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
 
 module RosettAi
+  # AI contribution attribution and disclosure management.
   module Authorship
     # Validates that Human-Reviewed-By differs from the commit author.
     #

data/lib/rosett_ai/authorship/trailer_generator.rb

@@ -16,6 +16,7 @@ module RosettAi
     # @author hugo
     # @author claude
     class TrailerGenerator
+      # @return [Object] Git trailer role identifiers for AI attribution.
       TRAILER_ROLES = RosettAi::Provenance::Entry::ALLOWED_ROLES
 
       # Generates a trailer string for a given engine.

data/lib/rosett_ai/backup/compressor.rb

@@ -8,9 +8,11 @@ require 'zlib'
 require 'fileutils'
 
 module RosettAi
+  # Configuration backup and restore functionality.
   module Backup
     # Factory and base for compression handlers
     class Compressor
+      # @return [Array] Algorithms constant.
       ALGORITHMS = ['zip', 'tar.gz', 'tar.xz'].freeze
 
       # Returns a compressor instance for the given algorithm.
@@ -114,6 +116,7 @@ module RosettAi
 
         File.open(output_path, 'wb', 0o644) do |file|
           Zlib::GzipWriter.wrap(file, gz_level) do |gz|
+            gz.mtime = 0 # Deterministic header for idempotency checking
             Gem::Package::TarWriter.new(gz) do |tar|
               files.each do |entry|
                 content = File.read(entry[:full_path])

data/lib/rosett_ai/backup/destination.rb

@@ -7,6 +7,7 @@ module RosettAi
   module Backup
     # Base class for backup destinations
     class Destination
+      # @return [Array] Supported schemes constant.
       SUPPORTED_SCHEMES = ['file', 's3', 'ssh', 'bup', 'https'].freeze
 
       attr_reader :uri

data/lib/rosett_ai/behaviour/manager.rb

@@ -10,6 +10,7 @@ require_relative '../validators/schema_validator'
 require_relative '../validators/behaviour_validator'
 
 module RosettAi
+  # Behaviour YAML file management and validation.
   module Behaviour
     # MCP-facing facade for behaviour file management.
     #

data/lib/rosett_ai/compiler/backend.rb

@@ -4,6 +4,7 @@
 # Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
 
 module RosettAi
+  # Compilation pipeline: behaviour YAML to engine-native rules.
   module Compiler
     # Abstract base class for compiler backends.
     #
@@ -74,6 +75,8 @@ module RosettAi
         false
       end
 
+      # Return the output file extension for this backend.
+      # @return [String]
       def file_extension
         case profile.output_format
         when 'json' then '.json'

data/lib/rosett_ai/compiler/backends/agents_md_backend.rb

@@ -16,6 +16,7 @@ module RosettAi
       # @author hugo
       # @author claude
       class AgentsMdBackend < Backend
+        # @return [String] Prefix for generated-file marker comments.
         MARKER_PREFIX = '<!-- rosett-ai-agents-md-managed'
 
         # Renders behaviour data into AGENTS.md format.

data/lib/rosett_ai/compiler/backends/claude_backend.rb

@@ -13,6 +13,7 @@ module RosettAi
       # source metadata, and the rosett-ai-claude-managed marker for idempotent
       # updates.
       class ClaudeBackend < Backend
+        # @return [String] Prefix for generated-file marker comments.
         MARKER_PREFIX = '<!-- rosett-ai-claude-managed'
 
         # Renders behaviour data into Claude Code rule format.

data/lib/rosett_ai/compiler/behaviour_compiler.rb

@@ -11,6 +11,7 @@ module RosettAi
     # backend to the Claude engine backend. Existing callers that instantiate
     # BehaviourCompiler continue to work without modification.
     class BehaviourCompiler < CompilationPipeline
+      # @return [String] Marker string identifying generated files.
       GENERATED_MARKER = '<!-- rosett-ai-claude-managed'
 
       # Backward-compatible wrapper that defaults to the Claude engine backend.

data/lib/rosett_ai/compiler/compilation_pipeline.rb

@@ -28,6 +28,7 @@ module RosettAi
       # globally would pollute ~/.claude/rules/ with empty files.
       PROJECT_ONLY_CATEGORIES = ['design'].freeze
 
+      # @return [Array] Allowed compilation scope values.
       VALID_SCOPES = [:global, :project].freeze
 
       attr_reader :source_dir, :target_dir, :schema_dir, :backend, :scope,
@@ -42,13 +43,6 @@ module RosettAi
       #   (e.g. global conf/ when compiling in project scope). Files from additional
       #   sources are included unless overridden by a file with the same basename
       #   in the primary source_dir. Empty by default for backward compatibility.
-      # @param source_dir [String, Pathname] primary conf/ root
-      # @param target_dir [String, Pathname] output directory
-      # @param schema_dir [String, Pathname] JSON Schema directory
-      # @param backend [RosettAi::Compiler::Backend] rendering backend
-      # @param scope [Symbol] compilation scope (:global or :project)
-      # @param additional_source_dirs [Array<String, Pathname>] extra source
-      #   directories (e.g. global conf/ when compiling in project scope)
       def initialize(source_dir:, target_dir:, schema_dir:, backend:, # rubocop:disable Metrics/ParameterLists
                      scope: :global, additional_source_dirs: [])
         validate_scope!(scope)

data/lib/rosett_ai/compiler/locale_compiler.rb

@@ -15,8 +15,10 @@ module RosettAi
     # keys into dotted paths, and generates platform-native locale files
     # for distribution.
     class LocaleCompiler
+      # @return [Array] CLDR plural form definitions per locale.
       PLURAL_FORMS = ['zero', 'one', 'two', 'few', 'many', 'other'].freeze
 
+      # @return [Hash] Gettext Plural-Forms header strings per locale.
       PLURAL_HEADERS = {
         'en' => 'nplurals=2; plural=(n != 1);',
         'fr' => 'nplurals=2; plural=(n > 1);',

data/lib/rosett_ai/compiler/target_profile.rb

@@ -15,6 +15,7 @@ module RosettAi
     # rendering options for a specific AI assistant target. Adding a new
     # target requires only a new YAML file — no code changes.
     class TargetProfile
+      # @return [Array] Attribute field names for this data object.
       FIELDS = [
         :name, :description, :backend, :engine_version, :output_format,
         :output_dir, :max_context_window, :rendering
@@ -81,14 +82,24 @@ module RosettAi
         (plugin_targets + engine_targets + legacy_targets).uniq.sort
       end
 
+      # Return the target profile path for a named engine.
+      #
+      # @param name [Object] the name
+      # @return [Pathname]
       def self.engine_target_path(name)
         RosettAi.root.join('conf', 'engines', name, 'target.yml')
       end
 
+      # Return the legacy target profile path.
+      #
+      # @param name [Object] the name
+      # @return [Pathname]
       def self.legacy_target_path(name)
         legacy_targets_dir.join("#{name}.yml")
       end
 
+      # Return the legacy targets directory.
+      # @return [Pathname]
       def self.legacy_targets_dir
         RosettAi.root.join('conf', 'targets')
       end

data/lib/rosett_ai/completion/generator.rb

@@ -4,6 +4,7 @@
 # Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
 
 module RosettAi
+  # Shell completion script generation.
   module Completion
     # Extracts command metadata from the Thor CLI registry for completion
     # script generation. This is the single source of truth for all
@@ -12,6 +13,7 @@ module RosettAi
     # @author hugo
     # @author claude
     class Generator
+      # @return [Array] Shell types supported for completion generation.
       SUPPORTED_SHELLS = ['bash', 'zsh', 'fish'].freeze
 
       # @return [Hash] command tree extracted from Thor CLI

data/lib/rosett_ai/completion/shells/zsh_generator.rb

@@ -5,6 +5,7 @@
 
 module RosettAi
   module Completion
+    # Shell-specific completion generators.
     module Shells
       # Generates zsh completion scripts from the Thor command tree.
       #

data/lib/rosett_ai/comply/checkers/cra_checker.rb

@@ -5,6 +5,7 @@
 
 module RosettAi
   module Comply
+    # Individual compliance checker implementations.
     module Checkers
       # CRA (Cyber Resilience Act) compliance checker.
       #

data/lib/rosett_ai/comply/checkers/license_checker.rb

@@ -15,10 +15,12 @@ module RosettAi
       # @author hugo
       # @author claude
       class LicenseChecker
+        # @return [Array] SPDX identifiers compatible with GPL-3.0-only.
         GPL_COMPATIBLE = [
           'MIT', 'BSD-2-Clause', 'BSD-3-Clause', 'Apache-2.0', 'ISC', 'Zlib', '0BSD', 'Unlicense', 'LGPL-2.0-only', 'LGPL-2.0-or-later', 'LGPL-2.1-only', 'LGPL-2.1-or-later', 'LGPL-3.0-only', 'LGPL-3.0-or-later', 'GPL-2.0-only', 'GPL-2.0-or-later', 'GPL-3.0-only', 'GPL-3.0-or-later', 'Ruby', 'PSF-2.0', 'Artistic-2.0', 'MPL-2.0'
         ].freeze
 
+        # @return [Array] SPDX identifiers incompatible with GPL-3.0-only.
         GPL_INCOMPATIBLE = [
           'AGPL-3.0-only', 'AGPL-3.0-or-later', 'SSPL-1.0', 'BUSL-1.1', 'Proprietary', 'CPAL-1.0', 'EUPL-1.1', 'EUPL-1.2'
         ].freeze

data/lib/rosett_ai/comply/checkers/spdx_header_checker.rb

@@ -14,9 +14,12 @@ module RosettAi
       # @author hugo
       # @author claude
       class SpdxHeaderChecker
+        # @return [Regexp] Regex matching valid SPDX license identifier lines.
         SPDX_PATTERN = /SPDX-License-Identifier:/
+        # @return [Integer] Number of lines to scan for SPDX headers.
         HEADER_SCAN_LINES = 10
 
+        # @return [Array] Glob patterns for source files requiring SPDX headers.
         SOURCE_GLOBS = [
           '**/*.rb',
           '**/*.yml',
@@ -24,6 +27,7 @@ module RosettAi
           '**/*.sh'
         ].freeze
 
+        # @return [Array] Directory names excluded from SPDX header scanning.
         SKIP_DIRS = [
           'vendor',
           'node_modules',

data/lib/rosett_ai/comply/runner.rb

@@ -4,6 +4,7 @@
 # Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
 
 module RosettAi
+  # Compliance verification for CRA, license, and SPDX requirements.
   module Comply
     # Orchestrates compliance checks across all registered checkers.
     #
@@ -13,6 +14,7 @@ module RosettAi
     # @author hugo
     # @author claude
     class Runner
+      # @return [Hash] Maps checker names to their implementation classes.
       CHECKER_MAP = {
         cra: Checkers::CraChecker,
         license: Checkers::LicenseChecker,

data/lib/rosett_ai/composition/composer.rb

@@ -4,6 +4,7 @@
 # Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
 
 module RosettAi
+  # Multi-source rule composition and merging.
   module Composition
     # Orchestrates behaviour composition: discovers behaviour files,
     # resolves scopes, sorts by priority, detects conflicts and

data/lib/rosett_ai/composition/lockfile.rb

@@ -12,6 +12,7 @@ module RosettAi
     # composition. Writes the exact composition result so that
     # `--frozen` compilations can reproduce the same output.
     class Lockfile
+      # @return [String] Default filename for this artifact.
       FILENAME = '.rosett-ai-lock.yml'
 
       # @param root [Pathname] project root directory

data/lib/rosett_ai/composition/merge_strategy.rb

@@ -12,6 +12,7 @@ module RosettAi
     # @author hugo
     # @author claude
     module MergeStrategy
+      # @return [Array] Available merge strategy names.
       STRATEGIES = ['first_wins', 'deep_merge', 'array_union'].freeze
 
       # Resolves the strategy class from a name string.

data/lib/rosett_ai/config/masking_secret_resolver.rb

@@ -12,8 +12,13 @@ module RosettAi
     # Follows the same interface as SecretResolver (resolve, resolve_all)
     # and uses the same deterministic string parsing — no regex.
     class MaskingSecretResolver
+      # @return [String] Placeholder string replacing resolved secrets in output.
       MASKED_VALUE = '***'
 
+      # Resolve the value for the given key.
+      #
+      # @param value [Object] the value
+      # @return [String]
       def resolve(value)
         return value unless value.is_a?(String)
         return value unless secret_reference?(value)
@@ -21,6 +26,10 @@ module RosettAi
         MASKED_VALUE
       end
 
+      # Resolve all secret references in the given hash.
+      #
+      # @param obj [Object] the obj
+      # @return [Hash]
       def resolve_all(obj)
         case obj
         when Hash  then obj.transform_values { |v| resolve_all(v) }

data/lib/rosett_ai/config/secret_resolver.rb

@@ -14,11 +14,15 @@ module RosettAi
     # - File backend: 0600 permissions, owned by Process.uid, 64 KiB cap
     # - Path backend: rejects ".." traversal
     class SecretResolver
+      # @return [String] Prefix marking a secret reference in config.
       SECRET_PREFIX = '${secret:'
+      # @return [String] Suffix marking a secret reference in config.
       SECRET_SUFFIX = '}'
+      # @return [Array] Supported secrets backend names.
       VALID_BACKENDS = ['env', 'file', 'path'].freeze
       MAX_FILE_SIZE = 65_536 # 64 KiB
 
+      # SecretError implementation.
       class SecretError < RosettAi::Error; end
 
       # Resolve a single secret reference string.

data/lib/rosett_ai/configuration.rb

@@ -10,9 +10,13 @@ module RosettAi
   # Manages hierarchical configuration for Rosett-AI
   # Supports global -> group -> project configuration inheritance
   class Configuration
+    # @return [String] Filename for the main settings file.
     SETTINGS_FILE = 'settings.json'
+    # @return [String] Filename for the local settings override file.
     LOCAL_SETTINGS_FILE = 'settings.local.json'
+    # @return [String] Relative path to the behaviour configuration directory.
     BEHAVIOUR_DIR = 'conf/behaviour'
+    # @return [String] Relative path to the JSON Schema directory.
     SCHEMA_DIR = 'conf/schemas'
 
     attr_reader :root_path

data/lib/rosett_ai/content/content_client.rb

@@ -12,6 +12,7 @@ module RosettAi
     # License key is sent as Bearer token. All requests use HTTPS.
     # Gracefully handles offline scenarios.
     class ContentClient
+      # @return [String] Default base URL for API requests.
       DEFAULT_BASE_URL = 'https://content.neatnerds.be/v1/'
 
       def initialize(license_key:, base_url: DEFAULT_BASE_URL)
@@ -22,6 +23,10 @@ module RosettAi
         end
       end
 
+      # Retrieve the content catalog from the remote source.
+      #
+      # @param tier [Object] the tier
+      # @return [Hash]
       def catalog(tier:)
         response = @connection.get('packs', tier: tier)
         raise RosettAi::ContentError, "Server error: #{response.status}" unless response.success?
@@ -31,6 +36,11 @@ module RosettAi
         raise RosettAi::ContentError, "Cannot reach content server: #{e.message}"
       end
 
+      # Download a content pack from the remote source.
+      #
+      # @param pack_name [Object] the pack name
+      # @param version [Object] the version
+      # @return [String]
       def download(pack_name, version:)
         response = @connection.get("packs/#{pack_name}/#{version}/download")
         raise RosettAi::ContentError, "Download failed: #{response.status}" unless response.success?
@@ -40,6 +50,11 @@ module RosettAi
         raise RosettAi::ContentError, "Cannot reach content server: #{e.message}"
       end
 
+      # Download the cryptographic signature for verification.
+      #
+      # @param pack_name [Object] the pack name
+      # @param version [Object] the version
+      # @return [String]
       def download_signature(pack_name, version:)
         response = @connection.get("packs/#{pack_name}/#{version}/signature")
         raise RosettAi::ContentError, "Signature download failed: #{response.status}" unless response.success?

data/lib/rosett_ai/content/pack_installer.rb

@@ -19,6 +19,7 @@ module RosettAi
     # - Atomic install: extract to temp dir, validate manifest, then move
     # - Uses same PUBLIC_KEY_HEX as LicenseKey for verification
     class PackInstaller
+      # @return [Object] Directory permission mode for secure directories.
       SAFE_DIR_MODE = 0o700
 
       # Verifies signature and installs a content pack atomically.

data/lib/rosett_ai/content/pack_manifest.rb

@@ -6,6 +6,7 @@
 require 'json_schemer'
 
 module RosettAi
+  # Content pack distribution and installation.
   module Content
     # Loads, validates, and provides access to content pack manifest data.
     #
@@ -19,18 +20,38 @@ module RosettAi
         validate!
       end
 
+      # Load a pack manifest from a YAML file.
+      #
+      # @param path [Object] the path
+      # @return [PackManifest]
       def self.from_file(path)
         data = RosettAi::YamlLoader.load_file(path)
         new(data)
       end
 
+      # Return the pack name.
+      # @return [String]
       def name = data['name']
+      # Return the version string.
+      # @return [String]
       def version = data['version']
+      # Return the minimum tier required for this pack.
+      # @return [String]
       def tier_required = data['tier_required']
+      # Return the human-readable description.
+      # @return [String]
       def description = data['description']
+      # Return the author name.
+      # @return [String]
       def author = data['author']
+      # Return the manifest contents hash.
+      # @return [Hash]
       def contents = data['contents'] || {}
+      # Return the list of behaviour file paths.
+      # @return [Array<String>]
       def behaviour_files = contents['behaviours'] || []
+      # Return the list of design file paths.
+      # @return [Array<String>]
       def design_files = contents['designs'] || []
 
       private

data/lib/rosett_ai/content_packs/manager.rb

@@ -4,6 +4,7 @@
 # Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
 
 module RosettAi
+  # Legacy content pack management (see {RosettAi::Content}).
   module ContentPacks
     # MCP-facing facade for content pack operations.
     #

data/lib/rosett_ai/dbus/compositor_detector.rb

@@ -18,12 +18,14 @@ module RosettAi
     # 6. DISPLAY set, WAYLAND_DISPLAY unset → :x11
     # 7. else → :unknown
     module CompositorDetector
+      # @return [Array] Methods for detecting the active compositor.
       COMPOSITOR_CHECKS = [
         { env: 'HYPRLAND_INSTANCE_SIGNATURE', type: :hyprland },
         { env: 'SWAYSOCK', type: :sway },
         { env: 'I3SOCK', type: :i3 }
       ].freeze
 
+      # @return [Hash] D-Bus service names for compositor detection.
       DBUS_NAMES = {
         'org.gnome.Shell' => :gnome,
         'org.kde.KWin' => :kwin

data/lib/rosett_ai/dbus/focus_adapters/base.rb

@@ -5,6 +5,7 @@
 
 module RosettAi
   module DBus
+    # Compositor-specific window focus tracking adapters.
     module FocusAdapters
       # Base class for compositor-specific focus adapters.
       #

data/lib/rosett_ai/dbus/focus_adapters/gnome_adapter.rb

@@ -15,6 +15,7 @@ module RosettAi
       # For GNOME >= 41, Eval is removed; falls back to xdotool + xprop.
       class GnomeAdapter < Base
         POLL_INTERVAL = 0.5 # seconds
+        # @return [Integer] GNOME version that removed Eval D-Bus interface.
         GNOME_EVAL_REMOVED_VERSION = 41
 
         def initialize
@@ -26,6 +27,8 @@ module RosettAi
           @use_xdotool = false
         end
 
+        # Start the adapter or service.
+        # @return [void]
         def start
           return if @running
 
@@ -38,6 +41,8 @@ module RosettAi
           @running = false
         end
 
+        # Stop the adapter or service.
+        # @return [void]
         def stop
           super
           @thread&.kill

data/lib/rosett_ai/dbus/focus_adapters/hyprland_adapter.rb

@@ -17,6 +17,8 @@ module RosettAi
           @thread = nil
         end
 
+        # Start the adapter or service.
+        # @return [void]
         def start
           return if @running
 
@@ -34,6 +36,8 @@ module RosettAi
           @running = false
         end
 
+        # Stop the adapter or service.
+        # @return [void]
         def stop
           super
           @thread&.kill

data/lib/rosett_ai/dbus/focus_adapters/i3_adapter.rb

@@ -17,6 +17,8 @@ module RosettAi
           @thread = nil
         end
 
+        # Start the adapter or service.
+        # @return [void]
         def start
           return if @running
 
@@ -33,6 +35,8 @@ module RosettAi
           @running = false
         end
 
+        # Stop the adapter or service.
+        # @return [void]
         def stop
           super
           @thread&.kill

data/lib/rosett_ai/dbus/focus_adapters/kwin_adapter.rb

@@ -20,6 +20,8 @@ module RosettAi
           @thread = nil
         end
 
+        # Start the adapter or service.
+        # @return [void]
         def start
           return if @running
 
@@ -32,6 +34,8 @@ module RosettAi
           @running = false
         end
 
+        # Stop the adapter or service.
+        # @return [void]
         def stop
           super
           @main_loop&.quit

data/lib/rosett_ai/dbus/focus_adapters/x11_adapter.rb

@@ -20,6 +20,8 @@ module RosettAi
           @last_window_id = nil
         end
 
+        # Start the adapter or service.
+        # @return [void]
         def start
           return if @running
           return unless xprop_available?
@@ -28,6 +30,8 @@ module RosettAi
           @thread = Thread.new { run_poll_loop }
         end
 
+        # Stop the adapter or service.
+        # @return [void]
         def stop
           super
           @thread&.kill