rosett-ai 1.3.3

data/conf/design/doctor.yml

@@ -0,0 +1,184 @@
+---
+name: doctor
+domain: core
+version: 0.2.0
+status: implemented
+priority: 2
+author: hugo
+created_at: "2026-03-16"
+modified_at: "2026-04-14"
+modified_by: claude opus-4.6
+depends_on:
+  - architecture
+  - security
+  - error_handling
+  - engine_architecture
+  - monitoring_observability
+#
+intent: |
+  Provide a single diagnostic command (`rai doctor`) that checks all runtime
+  prerequisites and reports actionable fixes for any issues found. Users
+  installing rosett-ai on a new machine, upgrading Ruby, or troubleshooting engine
+  failures need a one-stop health check that verifies Ruby version, gem
+  dependencies, file permissions, D-Bus availability, engine detection, and
+  cache integrity — without requiring them to know which subsystem is failing.
+
+  Without this command, users troubleshoot by trial and error: "Is it a Ruby
+  version mismatch? Missing gems? Wrong permissions?" This design replaces
+  guesswork with structured diagnostics that produce a pass/warn/fail report
+  per check, with specific remediation steps for each failure.
+
+  Doctor is the diagnostic layer — it inspects the runtime environment and
+  reports readiness. It does not modify state (no auto-fix). Monitoring
+  (monitoring_observability.yml) captures runtime telemetry during command
+  execution. Error handling (error_handling.yml) governs how errors are
+  displayed. Engine detection (engine_architecture.yml) provides the probe
+  logic that doctor invokes.
+#
+constraints:
+  - "Doctor must be read-only — it inspects and reports but never modifies
+    files, installs gems, or changes configuration"
+  - "Each check must be independently testable with a clear pass/warn/fail
+    verdict and a human-readable remediation message"
+  - "Doctor must work without any engine installed — it reports 'no engines
+    detected' as a warning, not an error"
+  - "Checks must complete within 5 seconds total on a standard system (no
+    network calls, no heavy computation)"
+  - "Output must be TTY-aware: formatted table with colour when interactive,
+    plain text with status codes when piped"
+  - "Doctor must not require elevated privileges — all checks operate within
+    the user's permission scope"
+  - "Exit code 0 when all checks pass, 1 when any check warns, 2 when any
+    check fails"
+  - "Each check class implements a common interface: #name, #run, #status,
+    #message, #remediation"
+  - "Checks are registered declaratively and executed in registration order"
+  - "Doctor must report the rai version and Ruby version at the top of output"
+  - "All remediation messages must be translatable via i18n keys"
+  - "This design governs environment diagnostics (checking readiness). Runtime
+    telemetry is governed by monitoring_observability.yml. Error display is
+    governed by error_handling.yml. Engine probing is governed by
+    engine_architecture.yml"
+#
+acceptance_criteria:
+  - "`rai doctor` runs all registered checks and displays a summary table"
+  - "Ruby version check verifies .ruby-version matches running Ruby"
+  - "Gem dependency check verifies all Gemfile.lock gems are installed"
+  - "File permission check verifies ~/.claude/ and ~/.config/rosett-ai/ are writable"
+  - "D-Bus availability check verifies session bus is accessible (warn if not)"
+  - "Engine detection check lists detected engines (warn if none found)"
+  - "Cache health check verifies cache directory exists and is writable"
+  - "Exit code 0 on all pass, 1 on any warn, 2 on any fail"
+  - "TTY-aware output: colour table when interactive, plain lines when piped"
+  - "Each check can be run individually via `rai doctor --check ruby_version`"
+  - "Output includes rai version and Ruby version header"
+  - "All remediation messages use i18n keys from locales/ directory"
+  - "`rai doctor --format json` outputs machine-readable results for CI"
+#
+examples:
+  - scenario: "User runs `rai doctor` on a correctly configured system"
+    expected: |
+      raictl 0.9.0 | Ruby 3.3.10 | Linux x86_64
+
+      ┌──────────────────────┬────────┬─────────────────────────────┐
+      │ Check                │ Status │ Details                     │
+      ├──────────────────────┼────────┼─────────────────────────────┤
+      │ Ruby version         │ PASS   │ 3.3.10 matches .ruby-version│
+      │ Gem dependencies     │ PASS   │ All 42 gems installed       │
+      │ File permissions     │ PASS   │ ~/.claude/ writable         │
+      │ D-Bus session bus    │ PASS   │ be.neatnerds.rosettai reachable │
+      │ Engine detection     │ PASS   │ claude (default), generic   │
+      │ Cache health         │ PASS   │ ~/.cache/rosett-ai/ writable     │
+      └──────────────────────┴────────┴─────────────────────────────┘
+
+      All 6 checks passed.
+    not: |
+      Raw exception output. Missing remediation for failures. Exit code 1
+      when everything is healthy.
+  - scenario: "User runs `rai doctor` with wrong Ruby version installed"
+    expected: |
+      Ruby version check fails with:
+      "FAIL: Ruby 3.2.3 detected, but .ruby-version requires 3.3.10.
+       Fix: rbenv install 3.3.10 && rbenv local 3.3.10"
+      Exit code 2. Other checks still run and report their status.
+    not: |
+      Doctor stops at first failure. No remediation suggestion.
+      Exit code 1 (should be 2 for failure).
+  - scenario: "User runs `rai doctor` on a headless server without D-Bus"
+    expected: |
+      D-Bus check warns: "WARN: D-Bus session bus not available. Desktop
+      integration features will be unavailable.
+      Fix: Install dbus and ensure DBUS_SESSION_BUS_ADDRESS is set."
+      Exit code 1 (warn). All other checks still run.
+    not: |
+      Doctor crashes because D-Bus is missing. D-Bus check reports FAIL
+      instead of WARN (D-Bus is optional).
+  - scenario: "CI pipeline runs `rai doctor --format json`"
+    expected: |
+      {"rai_version":"0.9.0","ruby_version":"3.3.10","checks":[
+        {"name":"ruby_version","status":"pass","message":"3.3.10 matches .ruby-version"},
+        {"name":"gem_dependencies","status":"pass","message":"All 42 gems installed"},
+        ...
+      ],"summary":{"pass":6,"warn":0,"fail":0}}
+    not: "Human-readable table output that CI cannot parse."
+  - scenario: "User runs a single check via `rai doctor --check cache_health`"
+    expected: |
+      Only the cache health check runs. Output shows single check result.
+      Exit code reflects that check's status only.
+    not: "All checks run despite --check filter. Unknown check name silently ignored."
+#
+anti_patterns:
+  - "Auto-fixing problems without user consent (doctor is read-only)"
+  - "Requiring network access for any check (all checks must be local)"
+  - "Stopping at the first failed check (always run all checks)"
+  - "Using raw Ruby exception output instead of structured remediation"
+  - "Hardcoding remediation messages instead of using i18n keys"
+  - "Treating optional features (D-Bus) as required (warn, not fail)"
+  - "Running checks that require elevated privileges"
+  - "Dynamic check discovery via ObjectSpace (register checks explicitly)"
+#
+gui_notes: |
+  Document interactions (cross-references):
+
+  1. error_handling.yml: exit codes follow the structured error hierarchy.
+     Doctor exit codes (0/1/2) align with the error code mapping.
+
+  2. engine_architecture.yml: engine detection check invokes the engine
+     detector to find installed AI tools.
+
+  3. monitoring_observability.yml: doctor itself emits telemetry events
+     (command_start, command_end) when telemetry is enabled.
+
+  4. security.yml: file permission checks verify security-relevant paths
+     (~/.claude/, ~/.config/rosett-ai/) have correct permissions.
+
+  5. architecture.yml: check registration follows the pluggable provider
+     pattern used throughout rosett-ai.
+
+  Module structure:
+
+  lib/rosett_ai/doctor.rb                          — Diagnostic runner (orchestrates checks)
+  lib/rosett_ai/doctor/check.rb                    — Base check interface
+  lib/rosett_ai/doctor/checks/ruby_version_check.rb
+  lib/rosett_ai/doctor/checks/gem_dependency_check.rb
+  lib/rosett_ai/doctor/checks/file_permission_check.rb
+  lib/rosett_ai/doctor/checks/dbus_availability_check.rb
+  lib/rosett_ai/doctor/checks/engine_detection_check.rb
+  lib/rosett_ai/doctor/checks/cache_health_check.rb
+  lib/rosett_ai/thor/tasks/doctor.rb               — CLI integration
+#
+preferences:
+  language: ruby
+  patterns:
+    - "Check interface pattern (#name, #run, #status, #message, #remediation)"
+    - "Declarative check registration"
+    - "TTY-aware output (TtyHelper)"
+    - "i18n remediation messages"
+    - "JSON output for CI integration"
+  testing: rspec with check pass/fail/warn scenarios, TTY vs pipe output,
+    exit code verification, JSON output format, and individual check filtering
+  gems:
+    - thor
+    - pastel
+    - tty-table
+    - i18n

data/conf/design/documentation.yml

@@ -0,0 +1,152 @@
+---
+name: documentation
+domain: documentation
+version: 0.2.0
+status: implemented
+priority: 5
+author: claude
+created_at: "2026-02-22"
+modified_at: "2026-03-17"
+modified_by: claude
+depends_on:
+  - architecture
+  - compiler
+  - error_handling
+
+intent: |
+  Provide end users with complete documentation for installing, configuring,
+  and using rosett-ai. The project currently has developer-facing docs (SETUP.md,
+  USAGE.md, CONFIGURATION.md) but lacks production-facing artifacts: man pages
+  for terminal discovery, installation guides for .deb users, and generated
+  API documentation for contributors.
+
+  Man pages are the Unix standard for command documentation. Users expect
+  'ma rai' to work after installing a .deb package. Without this, the tool
+  feels incomplete and forces users to find docs online.
+
+  API documentation via YARD enables contributors to understand the codebase
+  without reading every file. This is especially important for an open-source
+  GPL-3.0 project that invites community contributions.
+
+  An installation guide bridges the gap between "here is a .deb file" and
+  "here is a working rosett-ai setup". Without it, users must reverse-engineer
+  the setup process from developer docs.
+
+  A quick start guide (doc/QUICK_START.md) provides first-time users with a
+  5-minute path from installation to first successful compile. Unlike INSTALL.md
+  (which covers all installation methods) or the man page (which is a reference),
+  the quick start guide is a tutorial that walks through a single happy-path
+  scenario: install, init, author a behaviour, compile, verify. It targets users
+  who want to see rosett-ai produce output before reading comprehensive documentation.
+
+constraints:
+  - Man pages are authored in ronn-ng markdown format (doc/man/*.ronn)
+  - Man page build produces roff output at man/man1/rai.1
+  - The .deb package ships man pages at /usr/share/man/man1/rai.1.gz
+  - "YARD documentation generates without errors; minimum 40% of lib files have YARD tags (target 100%)"
+  - All user-facing documentation must be consistent with the current version (no stale version references)
+  - Documentation source files are versioned in git alongside code
+  - INSTALL.md covers .deb installation, APT repository setup, and post-install verification
+  - No documentation references features that don't exist yet (no aspirational docs)
+  - ronn-ng is a development dependency only (not runtime)
+  - Quick start guide must be completable in under 5 minutes by a new user
+  - "Quick start guide covers exactly one path: install, init, author, compile, verify"
+  - "Documentation generation processes trusted source files only — no external input accepted"
+
+acceptance_criteria:
+  - ma rai displays a well-formatted man page after .deb installation
+  - doc/man/rai.1.ronn exists with NAME, SYNOPSIS, DESCRIPTION, COMMANDS, OPTIONS, FILES, EXIT STATUS, and SEE ALSO sections
+  - A Rake task rake man generates man/man1/rai.1 from ronn source
+  - The .deb build process includes man page generation and installs to /usr/share/man/man1/
+  - .yardopts configuration exists with project-appropriate settings
+  - "yard doc generates HTML documentation; spec/yard_coverage_spec.rb enforces minimum 40% YARD tag coverage (target 100%)"
+  - INSTALL.md exists with sections for .deb install, APT repo config, manual install, and verification
+  - bin/raictl release prepare verifies documentation consistency (no stale version refs)
+  - All subcommands documented in man page match actual CLI help output
+  - doc/SETUP.md Ruby version matches .ruby-version (verified by CI)
+  - doc/QUICK_START.md exists with install, init, author, compile, verify sections
+  - Quick start guide uses only stable commands (no experimental features)
+
+examples:
+  - scenario: "User installs rosett-ai .deb and wants to learn available commands"
+    expected: |
+      $ ma rai
+      RAICTL(1)                    NeatNerds Manual                    RAICTL(1)
+
+      NAME
+        raictl - Rosett-AI
+
+      SYNOPSIS
+        raictl [--accessible] [--locale LOCALE] [--ui ADAPTER] COMMAND [ARGS]
+
+      DESCRIPTION
+        Configuration management tool for Claude Code workflows...
+
+      COMMANDS
+        version          Display rosett-ai version
+        compile          Compile YAML configurations into rule files
+        behaviour        Behaviour configuration management
+        ...
+    not: |
+      'ma rai' returns "No manual entry for Rosett-AI". Man page lists
+      commands that don't exist in the CLI. Man page version differs from
+      raictl version.
+
+  - scenario: "Contributor wants to understand the PathResolver API"
+    expected: |
+      $ yard doc
+      Files:          66
+      Modules:        15
+      Classes:        42
+      Methods:        180
+      YARD coverage spec enforces >= 40% (target 100%)
+
+      Open doc/api/index.html in browser → navigate to RosettAi::PathResolver
+      → see all public methods with param types and return values.
+    not: |
+      YARD coverage drops below 40% threshold. Generated docs reference
+      private implementation details.
+
+  - scenario: "New user wants to install rosett-ai on Debian Bookworm"
+    expected: |
+      User opens INSTALL.md, finds clear steps:
+      1. Add NeatNerds APT repository
+      2. Import GPG signing key
+      3. apt update && apt install rosett-ai
+      4. rai version (verify installation)
+      5. rai init --global (first-time setup)
+    not: |
+      INSTALL.md says "run bundle install" (that's developer setup, not user install).
+      INSTALL.md references features not yet available. Steps are out of order.
+
+  - scenario: "First-time user wants to see rosett-ai produce output immediately"
+    expected: |
+      User opens doc/QUICK_START.md, follows 5 steps:
+      1. apt install rosett-ai (or gem install)
+      2. rai init --global
+      3. rai behaviour manage add my_first_rule (creates a template)
+      4. rai compile --verbose (compiles to ~/.claude/rules/)
+      5. cat ~/.claude/rules/my_first_rule.md (sees compiled output)
+      Total time: under 5 minutes. User has a working rosett-ai setup.
+    not: |
+      Quick start requires reading 3 other documents first. Quick start
+      uses experimental commands. Quick start assumes prior knowledge of
+      YAML schemas or engine architecture.
+
+anti_patterns:
+  - Writing man pages in raw roff format (unreadable, unmaintainable)
+  - Generating documentation that references undocumented or private methods
+  - Shipping documentation with stale version numbers
+  - Duplicating CLI help text in man pages (generate from single source where possible)
+  - Creating documentation for features that don't exist yet (aspirational docs mislead users)
+  - Skipping man page from .deb package (users expect Unix conventions)
+
+preferences:
+  language: ruby
+  gems:
+    - ronn-ng
+    - yard
+  patterns:
+    - single_source_of_truth
+    - version_consistency_verification
+  testing: rspec for doc generation tasks, CI linting for version consistency

data/conf/design/engine_architecture.yml

@@ -0,0 +1,257 @@
+---
+name: engine_architecture
+domain: core
+version: 1.0.0
+status: implemented
+priority: 2
+author: hugo
+created_at: "2026-02-26"
+modified_at: "2026-04-14"
+modified_by: claude opus-4.6
+depends_on:
+  - architecture
+  - security
+  - testing
+  - compiler
+  - error_handling
+  - scope_hierarchy
+
+intent: |
+  Establish a pluggable engine architecture that enables rosett-ai to manage
+  configuration for multiple AI coding tools from a single set of
+  human-authored YAML source files. Each AI tool (Claude Code, Cursor,
+  Goose, AGENTS.md, Ollama, GPT-NeoX, etc.) is represented by an
+  independent engine — a self-contained gem with optional components.
+
+  The generic layer (conf/behaviour/, conf/design/) captures human intent:
+  behaviour rules, ethics, workflows, coding standards. This layer is
+  AI-tool-agnostic. Each engine translates the generic layer into its
+  tool's native format and writes to the tool's native filesystem location.
+
+  Engines are independently installable. Core rosett-ai has no LLM API
+  dependencies. The Claude engine brings the anthropic gem. The Ollama
+  engine brings an HTTP client for localhost. A minimal installation
+  with only the Generic engine produces plain markdown — no AI tool needed.
+
+  Engine authors need a comprehensive development guide (doc/ENGINE_DEVELOPMENT_GUIDE.md)
+  that covers manifest schema, component interfaces, testing patterns, and
+  packaging requirements. Without this guide, third-party engine development
+  requires reading Rosett-AI core source code — which is fragile and undocumented.
+  The guide serves as the Plugin SDK documentation for the engine architecture.
+
+  Engines are autodetectable. At init time or via bin/raictl engines detect,
+  raictl probes the system for installed AI tools and suggests a default
+  engine. Engines that support programmatic invocation (API or CLI) can
+  participate in quorum analysis via the separate quorum module.
+
+  This design supersedes the implicit Claude-only assumption and implements
+  the direction accepted as ADR-007.
+
+constraints:
+  - Each engine is a self-contained directory — no cross-engine dependencies
+  - Generic layer (behaviour, design YAML) contains only human intent — no engine-specific keys
+  - Engine-specific configuration lives in conf/engines/<name>/ — not in generic config
+  - Core rosett-ai has zero LLM API dependencies — API gems are engine-specific
+  - Existing Claude Code workflows must not break during incremental migration
+  - Engine components are optional — only implement what applies to the tool
+  - No forced common interface across engines — each implements relevant components only
+  - Autodetection is data-driven from manifest.yml — custom Ruby only when needed
+  - Quorum is a separate module (lib/rosett_ai/quorum/) — not part of engine interface
+  - Security constraints from security.yml apply to all engine code
+  - No ERB or eval-based templating for machine-parsed output (per ADR-006)
+  - Engine manifest schema must be documented and validated via JSON Schema
+  - doc/ENGINE_DEVELOPMENT_GUIDE.md must exist with manifest schema, component
+    interfaces, testing patterns, and packaging requirements
+  - "Engine target profiles must declare per-scope output directories: an
+    absolute path for global output and a relative path for scoped (local/
+    project) output resolved against the scope directory — see scope_hierarchy.yml"
+  - Engine detection must work at any scope level (global, local, project)
+
+acceptance_criteria:
+  - lib/rosett_ai/engines/claude/ directory contains backend, config_adapter, detector, and manifest
+  - lib/rosett_ai/engines/generic/ directory contains backend and manifest
+  - bin/raictl compile --engine claude produces identical output to current bin/raictl compile
+  - bin/raictl compile --engine generic produces identical output to current bin/raictl compile --target generic
+  - bin/raictl engines list shows all known engines with installed/detected status
+  - bin/raictl engines detect probes system and reports which AI tools are present
+  - bin/raictl init suggests default engine based on autodetection
+  - Compiling for an engine that does not support a generic feature emits a warning
+  - bin/raictl compile --engine cursor --strict fails if any unsupported features are present
+  - anthropic gem is not in rosett-ai.gemspec runtime dependencies
+  - bin/raictl adopt runs local structural checks without any engine or API configured
+  - bin/raictl adopt --api --engine claude invokes Claude API for analysis
+  - All 251+ existing tests pass after engine restructure with zero behavioural change
+  - conf/engines/claude/manifest.yml declares capabilities, detection, and execution metadata
+  - conf/schemas/engine_manifest_schema.json validates all engine manifests
+  - doc/ENGINE_DEVELOPMENT_GUIDE.md covers manifest schema, component interfaces,
+    testing patterns, gem packaging, and CI setup for third-party engines
+  - "Engine TargetProfile includes output_dirs hash with global (absolute)
+    and scoped (relative) paths"
+  - Engine detection works correctly at any scope level — an engine configured
+    at global scope is available to all local and project scopes
+
+examples:
+  - scenario: "User has only Claude Code installed, runs bin/raictl compile"
+    expected: |
+      Autodetected default engine is claude. Compiles behaviour YAML to
+      ~/.claude/rules/ in Claude markdown format. Output identical to
+      pre-restructure behaviour. No warnings.
+    not: "Compilation fails because no --engine flag provided. Output differs from before."
+  - scenario: "User installs Cursor alongside Claude, runs bin/raictl compile --engine cursor"
+    expected: |
+      Compiles behaviour YAML to .cursorrules in project root. Warns about
+      unsupported features (priority annotations, sensitive filtering).
+      Claude rules in ~/.claude/rules/ are unaffected.
+    not: "Cursor compilation modifies Claude rules. Unsupported features silently dropped."
+  - scenario: "CI pipeline runs bin/raictl compile --engine agents_md --strict"
+    expected: |
+      Compiles to AGENTS.md. If any behaviour uses features unsupported by
+      AGENTS.md engine, build fails with clear error listing unsupported features.
+    not: "Silently produces incomplete AGENTS.md. Build passes despite gaps."
+  - scenario: "Air-gapped government server with GPT-NeoX on vLLM, no internet"
+    expected: |
+      bin/raictl engines detect finds gpt_neox engine (vLLM endpoint configured).
+      bin/raictl adopt --api --engine gpt_neox analyses rules via local LLM.
+      No network calls to external services. Ollama not required.
+    not: "Adopt fails because no Anthropic API key. GPT-NeoX requires Ollama."
+  - scenario: "Claude engine declares per-scope output directories"
+    expected: |
+      Claude engine target profile contains:
+        output_dirs:
+          global: ~/.claude/rules/
+          scoped: .claude/rules/
+      bin/raictl compile --project resolves scoped path against project dir:
+        ~/projects/acme-api/.claude/rules/
+      bin/raictl compile --global writes to the absolute path: ~/.claude/rules/.
+    not: "All compiled output goes to ~/.claude/rules/ regardless of scope."
+
+anti_patterns:
+  - Engine B depending on Engine A (e.g. GPT-NeoX requiring Ollama)
+  - Generic layer containing engine-specific keys or extensions
+  - LLM API gems in core rosett-ai dependencies
+  - Assuming any specific engine is installed or configured
+  - Forced common interface that all engines must implement
+  - Config compilation logic outside the engine that owns the format
+  - Hardcoded engine paths instead of manifest-driven detection
+  - Hardcoded output directories instead of scope-aware output_dirs
+    (global absolute + scoped relative) from engine target profiles
+
+gui_notes: |
+  Engine directory structure:
+
+  lib/rosett_ai/engines/<name>/
+    backend.rb          — Compiler backend (renders YAML → tool-native format)
+    config_adapter.rb   — Settings compilation (tool-specific config files)
+    path_resolver.rb    — Output path resolution (where to write)
+    scaffolder.rb       — Init/scaffold (create tool directory structure)
+    detector.rb         — Autodetection (is this tool installed?)
+    executor.rb         — API/CLI invocation (for quorum, adopt --api)
+    validator.rb        — Output validation (is compiled output correct?)
+    manifest.yml        — Capability declaration, detection rules, execution metadata
+
+  All components are optional. Minimal engine (e.g. Cursor):
+    backend.rb + detector.rb + manifest.yml
+
+  Full engine (e.g. Claude):
+    All 8 files
+
+  Manifest structure:
+
+  name: claude
+  display_name: Claude Code
+  detection:
+    binaries: [claude]
+    config_dirs: [~/.claude]
+    env_vars: [ANTHROPIC_API_KEY]
+  capabilities:
+    behaviour_rules: true
+    design_constraints: true
+    priority_annotations: true
+    sensitive_filtering: true
+    source_metadata: true
+  execution:
+    invocable: true
+    methods: [api, cli]
+    api_gem: anthropic
+    cli_binary: claude
+    structured_output: true
+  output_dirs:
+    global: ~/.claude/rules/
+    scoped: .claude/rules/
+  supported_assets:
+    skills: { target: ".claude/skills/", format: "markdown" }
+    hooks: { target: ".claude/settings.json#hooks", format: "json" }
+    memory: { target: ".claude/memory/", format: "markdown" }
+  required_config:
+    - mcp_servers
+    - permissions
+    - api_settings
+
+  Quorum module (separate from engines):
+
+  lib/rosett_ai/quorum/
+    dispatcher.rb       — Send analysis to N engines in parallel
+    collector.rb        — Gather responses, handle timeouts
+    comparator.rb       — Determine consensus/disagreements
+    strategies/
+      adopt.rb          — Compare structured adopt findings
+      majority.rb       — Simple majority vote
+      unanimous.rb      — All must agree
+
+interactions:
+  - action: "Compile rules for a specific engine"
+    tui: "bin/raictl compile --engine claude"
+  - action: "List available engines"
+    tui: "bin/raictl engines list"
+  - action: "Detect installed AI tools"
+    tui: "bin/raictl engines detect"
+  - action: "Show engine status"
+    tui: "bin/raictl engines status"
+  - action: "Run local-only adopt"
+    tui: "bin/raictl adopt"
+  - action: "Run API-based adopt via specific engine"
+    tui: "bin/raictl adopt --api --engine claude"
+  - action: "Run quorum adopt"
+    tui: "bin/raictl adopt --api --quorum"
+
+preferences:
+  language: ruby
+  patterns:
+    - "Engine as namespace directory (lib/rosett_ai/engines/<name>/)"
+    - "Capability manifest with asset type contracts"
+    - "Data-driven detection from manifest.yml"
+    - "Optional components (only implement what applies)"
+    - "Strategy pattern for compiler backends"
+    - "No forced common interface across engines"
+  testing: rspec with per-engine specs, capability gap tests, manifest
+    validation, autodetection scenarios, and asset contract verification
+  gems:
+    - thor
+    - json_schemer
+    - zeitwerk
+
+implementation_notes: |
+  v1.2.0 implementation diverged from the original design in key areas:
+
+  1. Engine code lives in separate gems (rosett-ai-engine-claude,
+     rosett-ai-engine-agents-md) discovered via the plugin registry,
+     not in lib/rosett_ai/engines/<name>/ directories within core.
+
+  2. Core provides: base_config_compiler.rb, detector.rb, registry.rb
+     as abstract base infrastructure. Engine gems implement the
+     concrete backends.
+
+  3. Compiler backends (claude_backend, agents_md_backend, generic_backend)
+     live in lib/rosett_ai/compiler/backends/ as fallback implementations
+     for when engine gems are not installed.
+
+  4. Quorum module not yet implemented — deferred to post-v1.2.0.
+
+  5. Per-scope output_dirs (global absolute + scoped relative) not yet
+     in TargetProfile — uses a single output_dir field.
+
+  6. doc/ENGINE_DEVELOPMENT_GUIDE.md exists and covers manifest schema,
+     component interfaces, and gem packaging.
+
+  These divergences are intentional: the external-gem model proved
+  cleaner for distribution and versioning than embedded directories.