rosett-ai 1.3.3

data/conf/design/gui_plugins.yml

@@ -0,0 +1,475 @@
+---
+name: gui_plugins
+domain: ui
+version: 0.1.0
+status: implemented
+priority: 3
+author: hugo
+created_at: "2026-03-10"
+modified_at: "2026-03-16"
+modified_by: claude
+depends_on:
+  - architecture
+  - engine_architecture
+  - desktop_integration
+  - security
+  - distribution
+  - error_handling
+
+intent: |
+  Define the pluggable GUI architecture that treats desktop frontends as
+  first-class plugins — the same pattern used for engine plugins. GUI logic
+  must not live inside the rosett-ai core gem. Each desktop toolkit (GTK4, Qt6,
+  future web) is packaged as a separate gem (rosett-ai-gui-<toolkit>) that
+  self-registers via the plugin registry and implements a GuiContract.
+
+  GUIs are plugin managers. Every GUI must provide full lifecycle management
+  for all Rosett-AI plugin types: engines, MCP servers, and content packs. Users
+  install, remove, configure, and update plugins through the GUI. Under the
+  hood, plugin operations flow through D-Bus to Rosett-AI core, which delegates
+  to a PackageManager abstraction (apt, gem, future: dnf, brew, winget).
+
+  The D-Bus service and client remain in Rosett-AI core. The service enables
+  headless automation (CI, scripting, tiling WM integration) without any
+  GUI installed. GUI gems are D-Bus clients — they communicate exclusively
+  via D-Bus and never import core Ruby modules directly. This ensures that
+  any toolkit can be used without coupling to Ruby internals.
+
+  GUI gems ship all freedesktop.org XDG artifacts: .desktop files, scalable
+  icons, AppStream metainfo, and D-Bus activation service files. These are
+  installed to standard XDG paths by the package manager (apt) or by the
+  gem's post-install hook. All artifacts use the reverse-DNS identifier
+  be.neatnerds.rosettai (not be.neatnerds.rosettai — corrected to match the
+  actual domain neatnerds.be).
+
+  GUI gems are version-locked to Rosett-AI core via gemspec dependency:
+  spec.add_dependency 'rosett-ai', "= #{VERSION}". This guarantees D-Bus API
+  compatibility between the GUI client and the core service.
+
+  Package manager abstraction provides a uniform interface for installing
+  and removing system packages (apt-get), Ruby gems, and future package
+  managers (dnf, brew, winget). System package operations require PolicyKit
+  (pkexec) for privilege escalation — the GUI never runs as root.
+
+  Implementation phases:
+
+  Phase 1 — GuiContract + PackageManager abstraction in core:
+    lib/rosett_ai/plugins/gui_contract.rb (contract module)
+    lib/rosett_ai/package_manager/ (base, apt, gem backends)
+    D-Bus interface extensions for plugin management
+    Reverse-DNS rename: be.neatnerds.rosettai → be.neatnerds.rosettai
+
+  Phase 2 — Extract GTK4 code to rosett-ai-gui-gtk4 gem:
+    Move lib/rosett_ai/desktop/gtk4_app.rb → lib/rosett_ai_gui/gtk4/app.rb
+    Move lib/rosett_ai/desktop/gtk4_preferences.rb → lib/rosett_ai_gui/gtk4/preferences.rb
+    Move lib/rosett_ai/desktop/gui_logger.rb → lib/rosett_ai_gui/gtk4/gui_logger.rb
+    Add plugin management views (plugin_manager.rb)
+    Self-registration via rosett_ai_gui/gtk4/register.rb
+    XDG artifacts in share/ directory
+
+  Phase 3 — CI, packaging, validation:
+    GitLab CI pipeline for Rosett-AI-gui-gtk4 gem
+    Debian package build (rosett-ai-gui-gtk4)
+    AppStream and desktop-file validation in CI
+    Integration tests with mock D-Bus service
+
+  This design governs pluggable GUI gem architecture, plugin lifecycle
+  management, and PackageManager abstraction. The D-Bus service, compositor
+  adapters, and desktop service architecture are governed by
+  desktop_integration.yml. Engine plugin architecture is governed by
+  engine_architecture.yml. Error handling follows error_handling.yml.
+
+constraints:
+  - "No desktop GUI logic in Rosett-AI core gem — all GUI code lives in rosett-ai-gui-<toolkit> gems"
+  - "GUI plugins are separate gems following the pattern rosett-ai-gui-<toolkit>"
+  - "GUI gems are version-locked to core via gemspec — spec.add_dependency 'rosett-ai', '= VERSION'"
+  - "D-Bus service and D-Bus client library remain in Rosett-AI core"
+  - "GUI communicates exclusively via D-Bus — no direct Ruby API imports from core"
+  - "All XDG artifacts (.desktop, icons, metainfo, D-Bus service) ship inside the GUI gem or package"
+  - "Reverse-DNS identifier is be.neatnerds.rosettai everywhere — bus name, object paths, file names"
+  - "Package manager operations for system packages require PolicyKit (pkexec) for privilege escalation"
+  - "GUI gems self-register via Gem.find_files('rosett_ai_gui/*/register.rb') — same pattern as engine plugins"
+  - "Plugin management in GUI must support all plugin types — engines, MCP servers, content packs"
+  - "Security constraints from security.yml apply to all GUI plugin code and D-Bus interactions"
+  - "AppStream metainfo and .desktop files must pass their respective validators"
+  - "This design governs pluggable GUI gem architecture and plugin lifecycle.
+    D-Bus service and compositor adapters are governed by desktop_integration.yml"
+
+acceptance_criteria:
+  - "GuiContract module exists in lib/rosett_ai/plugins/gui_contract.rb"
+  - "GUI gem self-registers via Gem.find_files('rosett_ai_gui/*/register.rb')"
+  - "bin/raictl plugins list shows GUI plugins with type :gui alongside engine plugins"
+  - ".desktop file installed to share/applications/be.neatnerds.rosettai.desktop passes desktop-file-validate"
+  - "Scalable icon installed to share/icons/hicolor/scalable/apps/be.neatnerds.rosettai.svg"
+  - "AppStream metainfo at share/metainfo/be.neatnerds.rosettai.metainfo.xml passes appstreamcli validate"
+  - "GUI can list installed plugins of all types via D-Bus PluginManager interface"
+  - "GUI can install a plugin via D-Bus → PackageManager → apt-get or gem install"
+  - "GUI can remove a plugin via D-Bus → PackageManager → apt-get or gem uninstall"
+  - "GUI can open a configuration view for any installed plugin"
+  - "PackageManager::Apt backend wraps apt-get with pkexec for privilege escalation"
+  - "PackageManager::Gem backend wraps gem install/uninstall without privilege escalation"
+  - "All occurrences of be.neatnerds.rosettai renamed to be.neatnerds.rosettai in core and specs"
+  - "D-Bus service starts on be.neatnerds.rosettai bus name"
+  - "rosett-ai-gui-gtk4 gem installs and launches without Rosett-AI core needing any GUI dependencies"
+  - "Exit code 0 on success, 1 on plugin operation failure, 5 on missing GUI dependency"
+  - "TTY-aware output: formatted table for plugins list when interactive, JSON when piped"
+
+examples:
+  - scenario: "User installs rosett-ai-gui-gtk4 Debian package"
+    expected: |
+      Package installs the gem, .desktop file, icon, and metainfo to standard
+      XDG paths. GTK4 app appears in GNOME application menu. Launching it
+      connects to be.neatnerds.rosettai D-Bus service (auto-activates if needed).
+    not: "GUI code is bundled inside Rosett-AI core. .desktop file uses be.neatnerds.rosettai identifier."
+  - scenario: "User opens GUI and manages engine plugins"
+    expected: |
+      Plugin manager view lists installed engines (claude, generic, agents_md).
+      User clicks install, selects rosett-ai-engine-ollama from available packages.
+      GUI calls D-Bus PluginManager.Install('engine', 'ollama'). Core delegates
+      to PackageManager::Apt which runs pkexec apt-get install rosett-ai-engine-ollama.
+      After install, new engine appears in the list.
+    not: "GUI calls bin/raictl CLI directly. Installation runs without privilege escalation."
+  - scenario: "Developer creates a new rosett-ai-gui-web gem"
+    expected: |
+      Developer implements GuiContract in lib/rosett_ai_gui/web/gui.rb, adds
+      register.rb for self-registration. Gem is discoverable by core via
+      Gem.find_files. bin/raictl plugins list shows the web GUI alongside gtk4.
+      Web GUI communicates with core via D-Bus WebSocket bridge.
+    not: "Web GUI requires changes to Rosett-AI core. Developer must modify plugin registry manually."
+  - scenario: "User on Fedora installs rosett-ai-gui-gtk4 RPM"
+    expected: |
+      PackageManager::Dnf backend (future) handles installation. Same D-Bus
+      communication, same plugin management UI. Only the package manager
+      backend differs. Falls back to PackageManager::Gem if no system
+      package manager is configured.
+    not: "Installation fails because apt is hardcoded. GUI assumes Debian-based system."
+
+anti_patterns:
+  - "GUI code in Rosett-AI core gem (all GUI logic belongs in rosett-ai-gui-<toolkit> gems)"
+  - "GUI importing core Ruby modules directly (must communicate via D-Bus only)"
+  - "Hardcoding apt as the only package manager (use PackageManager abstraction)"
+  - "Using be.neatnerds.rosettai instead of be.neatnerds.rosettai (domain is neatnerds.be)"
+  - "Plugin management bypassing D-Bus (no direct CLI calls from GUI process)"
+  - "GUI running package operations as root (must use pkexec for privilege escalation)"
+  - "Tight coupling between GUI gem and a specific package manager backend"
+  - "Shipping XDG artifacts from Rosett-AI core instead of from the GUI gem"
+  - "Version mismatch between GUI gem and core (must be exact version lock)"
+
+gui_notes: |
+  Document interactions (cross-references):
+
+  1. desktop_integration.yml: gui_plugins governs pluggable GUI gem
+     architecture and plugin lifecycle. desktop_integration governs D-Bus
+     service, compositor adapters, and desktop service architecture.
+
+  2. engine_architecture.yml: engine plugins and GUI plugins share the
+     same self-registration pattern (Gem.find_files). GUI plugin management
+     covers engine install/remove/configure via D-Bus.
+
+  3. distribution.yml: GUI gems are distributed as Debian packages
+     alongside Rosett-AI core. Same Pulp repository, same CI pipeline pattern.
+
+  4. security.yml: GUI D-Bus interactions follow security constraints.
+     PackageManager uses array-form system() for subprocess spawning.
+
+  5. error_handling.yml: plugin operation errors follow the structured
+     error hierarchy. Exit codes for plugins list/install/remove commands.
+
+  6. content_packs.yml: GUI plugin management covers content pack
+     install/remove alongside engines and MCP servers.
+
+  GuiContract Definition:
+
+  module RosettAi::Plugins::GuiContract
+    include RosettAi::Plugins::Contract
+
+    def plugin_type = :gui
+
+    # Identity
+    def gui_name             # 'gtk4', 'qt6', 'web'
+    def application_id       # 'be.neatnerds.rosettai'
+    def toolkit              # 'gtk4', 'qt6', 'web'
+
+    # Lifecycle
+    def available?           # true if system dependencies are met
+    def launch(argv)         # Start the GUI application
+    def required_system_packages  # ['libgtk-4-1', 'libadwaita-1-0']
+    def manifest_path        # Path to conf/manifest.yml in the gem
+
+    # Plugin management (required — all GUIs must support this)
+    def plugin_list_view               # Show installed plugins of all types
+    def plugin_install_dialog(type)    # Install dialog for :engine / :mcp / :content
+    def plugin_remove_dialog(type, name)   # Removal confirmation for a plugin
+    def plugin_configure_view(type, name)  # Configuration view for a plugin
+  end
+
+  Package Manager Abstraction:
+
+  module RosettAi::PackageManager
+    class Base
+      def install(package_name)          # Install a package
+      def remove(package_name)           # Remove a package
+      def installed?(package_name)       # Check if a package is installed
+      def available_packages(pattern)    # Search available packages
+      def update_index                   # Refresh package list / cache
+    end
+
+    class Apt < Base
+      # Wraps apt-get via pkexec for privilege escalation
+      # Uses array-form system() — never string interpolation
+      # Parses dpkg-query for installed? checks
+    end
+
+    class Gem < Base
+      # Wraps Gem::Installer / Gem::Uninstaller
+      # No privilege escalation needed (user gem path)
+      # Fallback when no system package manager is available
+    end
+
+    # Future backends:
+    # class Dnf < Base   — Fedora/RHEL (dnf install)
+    # class Brew < Base  — macOS (brew install)
+    # class Winget < Base — Windows (winget install)
+  end
+
+  D-Bus PluginManager Interface (new, added to core service):
+
+  be.neatnerds.rosettai.PluginManager:
+    Methods:
+      ListPlugins(s type) -> a(sssa{sv})
+        # type: 'engine', 'gui', 'mcp', 'content'
+        # Returns array of (name, version, status, metadata)
+      InstallPlugin(s type, s name) -> (bs)
+        # Returns (success, message)
+      RemovePlugin(s type, s name) -> (bs)
+        # Returns (success, message)
+      GetPluginConfig(s type, s name) -> a{sv}
+        # Returns plugin configuration as dict
+      SetPluginConfig(s type, s name, a{sv} config) -> (bs)
+        # Updates plugin configuration
+    Signals:
+      PluginInstalled(s type, s name, s version)
+      PluginRemoved(s type, s name)
+      PluginConfigChanged(s type, s name)
+
+  GUI Gem Directory Structure:
+
+  rosett-ai-gui-gtk4/
+  ├── lib/rosett_ai_gui/gtk4/
+  │   ├── register.rb            # Self-registration with plugin registry
+  │   ├── gui.rb                 # GuiContract implementation
+  │   ├── app.rb                 # Gtk4App (extracted from core desktop/)
+  │   ├── preferences.rb         # Gtk4Preferences (extracted from core)
+  │   ├── gui_logger.rb          # GuiLogger (extracted from core)
+  │   ├── plugin_manager.rb      # Plugin management views (new)
+  │   └── version.rb             # Version constant (locked to core)
+  ├── conf/manifest.yml          # GUI capability manifest
+  ├── share/
+  │   ├── applications/
+  │   │   └── be.neatnerds.rosettai.desktop
+  │   ├── icons/hicolor/scalable/apps/
+  │   │   └── be.neatnerds.rosettai.svg
+  │   ├── metainfo/
+  │   │   └── be.neatnerds.rosettai.metainfo.xml
+  │   └── dbus-1/services/
+  │       └── be.neatnerds.rosettai.Gui.service
+  ├── packaging/scripts/
+  │   ├── postinst                # Install XDG artifacts, update caches
+  │   ├── prerm                   # Pre-removal cleanup
+  │   └── postrm                  # Post-removal cache updates
+  ├── spec/
+  │   ├── rosett_ai_gui/gtk4/
+  │   │   ├── gui_spec.rb
+  │   │   ├── app_spec.rb
+  │   │   ├── plugin_manager_spec.rb
+  │   │   └── register_spec.rb
+  │   └── support/
+  │       └── dbus_mock.rb        # Mock D-Bus service for tests
+  ├── rosett-ai-gui-gtk4.gemspec
+  ├── Gemfile
+  ├── .rubocop.yml
+  └── .reek.yml
+
+  GUI Manifest (conf/manifest.yml in rosett-ai-gui-gtk4):
+
+  name: gtk4
+  display_name: GTK4 Desktop App
+  plugin_type: gui
+  toolkit: gtk4
+  application_id: be.neatnerds.rosettai
+  required_system_packages:
+    - libgtk-4-1
+    - libadwaita-1-0
+    - gir1.2-gtk-4.0
+    - gir1.2-adw-1
+  capabilities:
+    plugin_management: true
+    preferences_dialog: true
+    system_tray: false       # SNI is in core D-Bus service
+    focus_monitoring: false   # Focus monitor is in core D-Bus service
+  xdg_artifacts:
+    desktop_file: share/applications/be.neatnerds.rosettai.desktop
+    icon_scalable: share/icons/hicolor/scalable/apps/be.neatnerds.rosettai.svg
+    metainfo: share/metainfo/be.neatnerds.rosettai.metainfo.xml
+
+  Reverse-DNS Rename Scope (be.neatnerds.rosettai → be.neatnerds.rosettai):
+
+  Core source files:
+    lib/rosett_ai/dbus/service.rb              — BUS_NAME constant
+    lib/rosett_ai/dbus/manager_interface.rb    — interface name string
+    lib/rosett_ai/dbus/focus_monitor_interface.rb — interface name string
+    lib/rosett_ai/dbus/status_notifier_interface.rb — interface name string
+    lib/rosett_ai/desktop/gtk4_app.rb          — APPLICATION_ID constant
+    lib/rosett_ai/desktop/dbus_client.rb       — bus name, object path
+    lib/rosett_ai/thor/tasks/dbus.rb           — bus name references
+
+  XDG artifact files (rename file + update contents):
+    share/applications/be.neatnerds.rosettai.desktop
+      → share/applications/be.neatnerds.rosettai.desktop
+    share/dbus-1/services/be.neatnerds.rosettai.service
+      → share/dbus-1/services/be.neatnerds.rosettai.service
+    share/dbus-1/interfaces/be.neatnerds.rosettai.xml
+      → share/dbus-1/interfaces/be.neatnerds.rosettai.xml
+
+  Spec files:
+    spec/rosett_ai/dbus/service_spec.rb
+    spec/rosett_ai/dbus/manager_interface_spec.rb
+    spec/rosett_ai/dbus/focus_monitor_interface_spec.rb
+    spec/rosett_ai/dbus/status_notifier_interface_spec.rb
+    spec/rosett_ai/desktop/dbus_client_spec.rb
+    spec/rosett_ai/desktop/gtk4_app_spec.rb
+    spec/rosett_ai/thor/tasks/dbus_spec.rb
+
+  Documentation:
+    CLAUDE.md, README.md, CHANGELOG.md, DESKTOP.md
+    doc/man/rai.1.ronn
+    doc/IMPLEMENTATION_PLAN.md, doc/ARCHITECTURE.md
+    conf/design/desktop_integration.yml
+
+  Self-Registration (lib/rosett_ai_gui/gtk4/register.rb):
+
+  module RosettAiGui
+    module Gtk4
+      class Register
+        def self.call(registry)
+          registry.register(
+            name: 'gtk4',
+            type: :gui,
+            klass: -> { require 'rosett_ai_gui/gtk4/gui'; RosettAiGui::Gtk4::Gui },
+            manifest: File.expand_path('../../conf/manifest.yml', __dir__)
+          )
+        end
+      end
+    end
+  end
+
+  Gemspec Pattern (rosett-ai-gui-gtk4.gemspec):
+
+  Gem::Specification.new do |spec|
+    spec.name          = 'rosett-ai-gui-gtk4'
+    spec.version       = RosettAiGui::Gtk4::VERSION
+    spec.summary       = 'GTK4 desktop interface for Rosett-AI'
+    spec.license       = 'GPL-3.0-only'
+    spec.authors       = ['Hugo Antonio Sepulveda Manriquez']
+    spec.email         = ['hugo@neatnerds.be']
+
+    spec.add_dependency 'rosett-ai', "= #{RosettAiGui::Gtk4::VERSION}"
+    spec.add_dependency 'gtk4', '~> 4.2'
+    spec.add_dependency 'adwaita', '~> 0.5'
+
+    spec.metadata['rubygems_mfa_required'] = 'true'
+  end
+
+interactions:
+  - action: "List installed plugins"
+    tui: "bin/raictl plugins list"
+    gtk4: "Plugin Manager view in main window"
+    qt6: "KCM plugin management panel"
+  - action: "Install a new engine"
+    tui: "bin/raictl plugins install engine ollama"
+    gtk4: "Plugin Manager → Install → select engine from list"
+    qt6: "KCM plugin panel → Install button → engine list"
+  - action: "Remove a plugin"
+    tui: "bin/raictl plugins remove engine ollama"
+    gtk4: "Plugin Manager → select plugin → Remove button → confirmation dialog"
+    qt6: "KCM plugin panel → select plugin → Remove → confirmation"
+  - action: "Configure a plugin"
+    tui: "bin/raictl plugins configure engine claude"
+    gtk4: "Plugin Manager → select plugin → Configure button → settings view"
+    qt6: "KCM plugin panel → select plugin → Configure → settings form"
+  - action: "Launch GUI application"
+    tui: "bin/raictl gui launch gtk4"
+    gtk4: "Desktop menu entry or bin/rai-gtk4"
+    qt6: "System Settings → rosett-ai module or bin/rai-qt6"
+
+accessibility:
+  roles:
+    - element: "plugin_list"
+      role: "listbox"
+      label: "Installed plugins"
+      description: "List of all installed rai plugins grouped by type"
+    - element: "plugin_install_button"
+      role: "button"
+      label: "Install plugin"
+      description: "Opens the plugin installation dialog"
+    - element: "plugin_remove_button"
+      role: "button"
+      label: "Remove plugin"
+      description: "Removes the selected plugin after confirmation"
+    - element: "plugin_configure_button"
+      role: "button"
+      label: "Configure plugin"
+      description: "Opens configuration view for the selected plugin"
+    - element: "package_manager_status"
+      role: "status"
+      label: "Package manager status"
+      description: "Shows which package manager backend is active and its state"
+  keyboard:
+    - key: "Tab"
+      action: "Navigate between plugin list and action buttons"
+    - key: "Arrow keys"
+      action: "Navigate plugin list items"
+    - key: "Enter"
+      action: "Activate selected button or open plugin details"
+    - key: "Delete"
+      action: "Remove selected plugin (with confirmation)"
+    - key: "Escape"
+      action: "Close dialog or cancel operation"
+  announcements:
+    - event: "plugin_installed"
+      announce: "Plugin <name> installed successfully"
+      priority: "polite"
+    - event: "plugin_removed"
+      announce: "Plugin <name> removed"
+      priority: "polite"
+    - event: "plugin_install_failed"
+      announce: "Failed to install plugin <name>: <error>"
+      priority: "assertive"
+    - event: "privilege_escalation"
+      announce: "Authentication required to install system package"
+      priority: "assertive"
+  target_sizes:
+    minimum: "24x24dp"
+    recommended: "44x44dp"
+  timing:
+    no_time_limits: true
+    animations_respect_prefers_reduced_motion: true
+
+preferences:
+  language: ruby
+  patterns:
+    - "GUI as plugin (self-registering gem, GuiContract)"
+    - "PackageManager abstraction (Apt, Gem, future: Dnf, Brew)"
+    - "D-Bus exclusive IPC (no direct Ruby API imports)"
+    - "Reverse-DNS naming (be.neatnerds.rosettai)"
+    - "XDG compliance for desktop artifacts"
+    - "Version-locked gems (exact dependency on core)"
+    - "Privilege escalation via PolicyKit (pkexec)"
+  testing: rspec with mock D-Bus service, GuiContract compliance tests,
+    PackageManager backend scenarios, plugin install/remove lifecycle,
+    XDG artifact validation, version lock enforcement, and privilege
+    escalation handling
+  gems:
+    - ruby-dbus (core, for D-Bus client)
+    - gtk4 (rosett-ai-gui-gtk4 only)
+    - adwaita (rosett-ai-gui-gtk4 only)

data/conf/design/i18n.yml

@@ -0,0 +1,84 @@
+---
+name: i18n
+domain: i18n
+version: 1.1.0
+status: implemented
+priority: 3
+author: hugo
+created_at: "2026-02-18"
+modified_at: "2026-03-17"
+modified_by: claude
+depends_on:
+  - architecture
+  - compiler
+
+intent: |
+  Enable rosett-ai to support any language in the world across all surfaces: UI
+  strings (TUI + GUI), CLI output, documentation, and validation messages.
+  The approach uses ruby-i18n YAML as the single source of truth, compiled
+  to platform-native formats for each GUI toolkit (gettext for GTK4/KDE,
+  Qt Linguist for Qt6). This follows the 'author once, compile down'
+  principle already established for behaviour and design compilation.
+
+constraints:
+  - All user-facing strings must be externalized to locale files (never hardcoded)
+  - ruby-i18n YAML format is the single source of truth for all translations
+  - Locale files must be compiled to platform-native formats (gettext .po/.mo, Qt .ts/.qm)
+  - CLDR plural rules must be used for correct pluralization in all languages
+  - RTL languages (Arabic, Hebrew, Persian, Urdu) must be fully supported
+  - All files must be UTF-8 encoded — no exceptions, no legacy encoding support
+  - English (en) is always the fallback locale
+  - Missing translations must fall back gracefully and never crash the application
+  - Locale resolution order is explicit flag > config file > LANG env > English fallback
+  - All I/O assumes UTF-8 (enforced at startup with a terminal capability check)
+
+acceptance_criteria:
+  - locales/en.yml exists with complete English translations for all UI strings
+  - bin/raictl compile --locales produces gettext and Qt Linguist files
+  - bin/raictl --locale fr displays French strings (with English fallback for missing keys)
+  - Pluralization works correctly for Arabic (6 forms) and Polish (4 forms)
+  - RTL text direction is correctly applied when locale is ar, he, fa, or ur
+  - Terminal UTF-8 capability is checked at startup with clear error if unsupported
+  - bin/raictl documentation translate --from en --to fr produces draft translation
+  - Fallback chain works correctly (nl_BE > nl > en)
+
+examples:
+  - scenario: "User runs bin/raictl compile on a French system (LANG=fr_FR.UTF-8)"
+    expected: |
+      CLI output is in French. 'Compiled 3 rules successfully' becomes
+      '3 règles compilées avec succès'. Validation errors are in French.
+    not: "Output is in English despite French locale. Mixed English/French output."
+  - scenario: "Arabic translation has 6 plural forms for 'rules compiled'"
+    expected: |
+      0 rules: zero form. 1 rule: one form. 2 rules: two form.
+      3-10 rules: few form. 11-99 rules: many form. 100+ rules: other form.
+    not: "Only singular/plural distinction. Wrong form used for Arabic numbers."
+  - scenario: "Developer adds a new CLI command but forgets to add locale strings"
+    expected: |
+      English key is used as fallback. Log warning about missing translation
+      key in development mode. rubocop-i18n (if available) flags hardcoded strings.
+    not: "Application crashes with MissingTranslationData error."
+  - scenario: "User wants to help translate rosett-ai to their language"
+    expected: |
+      Copy locales/en.yml to locales/xx.yml. Translate strings. Submit PR.
+      bin/raictl compile --locales generates platform-native files from new locale.
+    not: "Translator must understand gettext .po format or Qt Linguist .ts format."
+
+anti_patterns:
+  - Hardcoded user-facing strings in source code
+  - Using gettext or Qt Linguist as source format (these are compilation targets)
+  - Assuming English plural rules (singular/plural only) for all languages
+  - Ignoring RTL text direction for Arabic, Hebrew, Persian, Urdu
+  - Legacy encoding support (Shift_JIS, ISO-8859-1, etc.)
+  - Crashing on missing translation keys instead of falling back
+  - Locale detection that ignores system LANG environment variable
+
+preferences:
+  language: ruby
+  gems:
+    - i18n
+    - gettext
+  patterns:
+    - single_source_of_truth_locale_files
+    - compile_to_platform_native
+    - graceful_fallback_chain

data/conf/design/integration_testing.yml

@@ -0,0 +1,56 @@
+---
+name: integration_testing
+domain: core
+version: "1.1.0"
+status: implemented
+intent: |
+  Define a comprehensive integration testing strategy for rosett-ai that ensures
+  .deb packages are built from source and verified against InSpec controls
+  inside isolated Vagrant/libvirt VMs. The strategy supports both local developer
+  workstations and GitLab CI, and is gated so that no CLI change can land on
+  main without passing integration verification.
+
+  This design addresses a systemic gap discovered on 2026-04-07/08: all 37
+  InSpec controls were authored speculatively between 2026-03-09 and
+  2026-03-23, never executed against a real VM, and accumulated 26 breaking
+  CLI changes over 30 days before the first real run. Three controls were
+  wrong at the moment they were written.
+
+constraints:
+  - "Must use Vagrant with libvirt provider (KVM/QEMU) for isolation"
+  - "Must install pre-built .deb from pkg/ directory (data_path in kitchen.yml)"
+  - "Must install and test ALL engine .debs when present"
+  - "Must run as a GitLab CI stage, blocking merge to main on failure"
+  - "Must be runnable locally via a single command"
+  - "Provisioner must handle locale, ownership, and build deps automatically"
+  - "CI job must complete in under 20 minutes"
+  - "Must detect when CLI changes break InSpec controls before merge"
+  - "kitchen-vagrant pinned to 1.14.2 (last MPL-2.0 compatible with Vagrant 2.3.x)"
+
+acceptance_criteria:
+  - "`rake build:package && BUNDLE_GEMFILE=Gemfile.integration bundle exec kitchen test` passes all controls"
+  - "GitLab CI includes an integration stage with kitchen verify"
+  - "kitchen.yml uses vagrant driver with libvirt provider"
+  - "README or INSTALL.md documents how to run integration tests locally"
+
+examples:
+  - scenario: "Developer modifies Thor subcommand structure"
+    expected: "CI warns about stale InSpec controls referencing old command names"
+  - scenario: "CI runs on merge request to main"
+    expected: "Integration stage installs .deb in clean VM, runs kitchen verify, blocks merge on failure"
+  - scenario: "Developer runs integration tests locally"
+    expected: "`BUNDLE_GEMFILE=Gemfile.integration bundle exec kitchen test` completes via Vagrant/libvirt"
+
+preferences:
+  language: ruby
+  patterns:
+    - "kitchen.yml uses vagrant driver with libvirt provider"
+    - "Two suites: rai-context (path resolution) and rai-commands (CLI commands)"
+    - "provision.sh is the single source of truth for VM setup"
+    - "data_path: pkg syncs pre-built .deb packages to guest"
+  testing: "InSpec 4.x via kitchen-inspec"
+
+anti_patterns:
+  - "Do not write InSpec controls without running them against a real target"
+  - "Do not modify CLI subcommand structure without grepping test/integration/"
+  - "Do not use sudo in InSpec verifier (breaks shell builtins)"