rosett-ai 1.3.3

data/doc/USAGE.md

@@ -0,0 +1,545 @@
+# Rosett-AI - Usage Guide
+
+## CLI Commands
+
+The `rosett-ai` CLI provides various commands for managing AI-assisted development configurations.
+
+### Getting Help
+
+```bash
+# Show all commands
+bin/raictl help
+
+# Show help for a specific command
+bin/raictl help behaviour
+bin/raictl behaviour help display
+```
+
+### Version
+
+```bash
+bin/raictl version
+# or
+bin/raictl -v
+bin/raictl --version
+```
+
+## Documentation Commands
+
+Manage project documentation.
+
+### Update Documentation
+
+Scan for changes and update documentation files:
+
+```bash
+# Basic update
+bin/raictl documentation update
+
+# Dry run (show what would change)
+bin/raictl documentation update --dry-run
+
+# Update for specific locale
+bin/raictl documentation update --locale=nl
+
+# Update all locales
+bin/raictl documentation update --all-locales
+```
+
+### Check Documentation Status
+
+```bash
+bin/raictl documentation status
+```
+
+## Behaviour Commands
+
+Manage behaviour configuration files.
+
+### Display Behaviours
+
+Show all configured behaviours in a table:
+
+```bash
+# Table format (default)
+bin/raictl behaviour display
+
+# JSON format
+bin/raictl behaviour display --format=json
+
+# YAML format
+bin/raictl behaviour display --format=yaml
+```
+
+### List Behaviours
+
+```bash
+bin/raictl behaviour list
+```
+
+### Show Specific Behaviour
+
+```bash
+bin/raictl behaviour show my_behaviour
+```
+
+### Validate Behaviours
+
+```bash
+# Validate all behaviour files
+bin/raictl behaviour validate
+
+# Validate specific behaviour
+bin/raictl behaviour validate my_behaviour
+```
+
+### Manage Behaviours
+
+#### Add New Behaviour
+
+```bash
+# Interactive mode
+bin/raictl behaviour manage add new_behaviour
+
+# With description
+bin/raictl behaviour manage add new_behaviour --description="My new behaviour rules"
+
+# With author
+bin/raictl behaviour manage add new_behaviour --author="john.doe"
+```
+
+#### Modify Existing Behaviour
+
+```bash
+bin/raictl behaviour manage modify existing_behaviour
+```
+
+This opens the behaviour file in your `$EDITOR` for editing.
+
+#### Delete Behaviour
+
+```bash
+# With confirmation prompt
+bin/raictl behaviour manage delete old_behaviour
+
+# Skip confirmation
+bin/raictl behaviour manage delete old_behaviour --force
+```
+
+## Init Commands
+
+Initialize Claude Code directory structure (idempotent).
+
+### Global Setup
+
+```bash
+# Set up ~/.claude/ structure
+bin/raictl init --global
+
+# Without compilation
+bin/raictl init --global --no-compile
+```
+
+### Local Setup
+
+```bash
+# Set up .claude/ in current project
+bin/raictl init --local
+
+# Without compilation
+bin/raictl init --local --no-compile
+```
+
+### Project Setup
+
+```bash
+# Set up .rosett-ai/ project structure (config.yml, conf/behaviour/, conf/design/)
+bin/raictl init --project
+```
+
+### Both
+
+```bash
+# Set up both global and local structures
+bin/raictl init --global --local
+```
+
+### Flags
+
+| Flag | Effect |
+|------|--------|
+| `--global` | Set up global `~/.claude/` structure |
+| `--local` | Set up project-local `.claude/` structure |
+| `--project` | Set up `.rosett-ai/` project structure with `config.yml` |
+| `--no-compile` | Skip the compile step after setup |
+
+## Backup Commands
+
+Back up Claude Code directory structure and generated assets.
+
+### Create Backup
+
+```bash
+# Back up global ~/.claude/ structure
+bin/raictl backup --global
+
+# Back up project-local .claude/ and CLAUDE.md
+bin/raictl backup --local
+
+# Back up both scopes
+bin/raictl backup --global --local
+
+# Use tar.gz compression
+bin/raictl backup --global --compression=tar.gz
+
+# Use tar.xz compression
+bin/raictl backup --global --compression=tar.xz
+
+# Set compression level (0-9)
+bin/raictl backup --global --compression=tar.gz --compression-ratio=9
+
+# Custom destination
+bin/raictl backup --global --destination=/path/to/backup.zip
+
+# URI-prefixed destination
+bin/raictl backup --global --destination=file:///tmp/backup.tar.gz
+```
+
+### Flags
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--global` | `false` | Back up `~/.claude/` structure |
+| `--local` | `false` | Back up project `.claude/` and `CLAUDE.md` |
+| `--compression` | `zip` | Compression algorithm: `zip`, `tar.gz`, `tar.xz` |
+| `--compression-ratio` | (default) | Compression level (0-9, if supported) |
+| `--destination` | `nncc_backup_<date>.<ext>` | Output path or URI |
+
+### Supported Compression Algorithms
+
+| Algorithm | Extension | Availability |
+|-----------|-----------|--------------|
+| `zip` | `.zip` | Requires `rubyzip` gem (bundled) |
+| `tar.gz` | `.tar.gz` | Always available (Ruby stdlib) |
+| `tar.xz` | `.tar.xz` | Requires `xz` command on system |
+
+### Destination URI Schemes
+
+| Scheme | Status |
+|--------|--------|
+| `file://` | Fully supported |
+| `s3://` | Planned (not yet implemented) |
+| `ssh://` | Planned (not yet implemented) |
+| `bup://` | Planned (not yet implemented) |
+| `https://` | Planned (not yet implemented) |
+
+### Idempotent Behaviour
+
+Running backup twice with the same content will report "OK (unchanged)" and skip re-creation. Changed content will overwrite and report "Updated".
+
+## Build Commands
+
+Build and package rosett-ai for distribution as a self-contained Debian package.
+
+The build pipeline uses [fpm](https://github.com/jordansissel/fpm) for packaging and
+[ruby-build](https://github.com/rbenv/ruby-build) to compile an embedded Ruby runtime.
+The resulting `.deb` includes everything needed to run rosett-ai — no system Ruby required.
+
+### Build Package
+
+```bash
+# Build with defaults (reads Ruby version from .ruby-version)
+bin/raictl build package
+
+# Build with verbose output
+bin/raictl build package --verbose
+
+# Clean staging directory before building
+bin/raictl build package --clean
+
+# Override Ruby version
+bin/raictl build package --ruby-version 3.3.10
+
+# Build for a specific architecture
+bin/raictl build package --architecture arm64
+
+# Custom output directory
+bin/raictl build package --output-dir /tmp/pkg
+
+# Set build iteration (release number)
+bin/raictl build package --build-iteration 2
+
+# Combined flags
+bin/raictl build package --clean --verbose --architecture amd64
+```
+
+### Flags
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--verbose` | bool | `false` | Show detailed build output |
+| `--clean` | bool | `false` | Clean staging directory before building |
+| `--ruby-version` | string | `.ruby-version` | Ruby version to compile |
+| `--architecture` | string | auto-detect | Target architecture (amd64, arm64) |
+| `--output-dir` | string | `pkg` | Directory for the produced .deb file |
+| `--build-iteration` | numeric | `1` | Package build iteration (release number) |
+| `--variant` | string | `core` | Package variant: `core`, `gtk4`, `qt6` |
+
+Run `bin/raictl build help package` for the full list.
+
+### Build Pipeline
+
+The build proceeds through these stages:
+
+1. **Validate** — checks that `ruby-build`, `fpm`, `fakeroot`, `dpkg-deb`, and `rsync` are available
+2. **Compile Ruby** — runs `ruby-build` to install Ruby into `tmp/staging/opt/rosett-ai/embedded/`
+3. **Sync application** — copies source tree (excluding dev/test/CI files) to `tmp/staging/opt/rosett-ai/app/`
+4. **Install gems** — runs `bundle install --deployment` using the embedded Ruby
+5. **Install wrapper** — copies `packaging/wrapper.sh` as `/opt/rosett-ai/bin/raictl`
+6. **Package** — invokes `fpm` to produce a `.deb` with maintainer scripts and xz compression
+
+### Package Layout
+
+| Path | Contents |
+|------|----------|
+| `/opt/rosett-ai/embedded/` | Compiled Ruby runtime |
+| `/opt/rosett-ai/app/` | Application source and vendored gems |
+| `/opt/rosett-ai/bin/raictl` | Wrapper script |
+| `/opt/rosett-ai/etc/` | Default configuration files |
+| `/etc/rosett-ai/` | System configuration (created by postinst) |
+| `/usr/local/bin/raictl` | Symlink (created by postinst) |
+
+### APT Lifecycle
+
+| Operation | Behaviour |
+|-----------|-----------|
+| `dpkg -i nncc_*.deb` | Installs to `/opt/rosett-ai`, creates symlink and `/etc/rosett-ai/` |
+| `dpkg -r rosett-ai` | Removes files but preserves `/etc/rosett-ai/` |
+| `dpkg --purge rosett-ai` | Removes everything including `/etc/rosett-ai/` |
+
+### Build Dependencies
+
+These tools must be available on the build host:
+
+| Tool | Package | Purpose | Reference |
+|------|---------|---------|-----------|
+| `ruby-build` | (manual install) | Compile Ruby from source | [github.com/rbenv/ruby-build](https://github.com/rbenv/ruby-build) |
+| `fpm` | `gem install fpm` | Create .deb packages | [github.com/jordansissel/fpm](https://github.com/jordansissel/fpm) |
+| `fakeroot` | `fakeroot` | Simulate root for packaging | [wiki.debian.org/FakeRoot](https://wiki.debian.org/FakeRoot) |
+| `dpkg-deb` | `dpkg-dev` | Low-level .deb manipulation | [man7.org/dpkg-deb](https://man7.org/linux/man-pages/man1/dpkg-deb.1.html) |
+| `rsync` | `rsync` | Efficient file synchronisation | [rsync.samba.org](https://rsync.samba.org/) |
+
+### Runtime Dependencies (declared in .deb)
+
+| Package | Purpose |
+|---------|---------|
+| `libc6` | GNU C Library |
+| `libssl3` | OpenSSL shared libraries |
+| `zlib1g` | Compression library |
+| `libyaml-0-2` | YAML parsing (required by Psych gem) |
+
+## Compile with Different Engines
+
+raictl supports 10 compilation engines. Use `--engine` to select:
+
+```bash
+# Claude Code (default)
+bin/raictl compile --engine claude
+
+# Generic AI assistant
+bin/raictl compile --engine generic
+
+# AGENTS.md vendor-neutral format
+bin/raictl compile --engine agents_md
+
+# Local model engines
+bin/raictl compile --engine ollama
+bin/raictl compile --engine gpt_neox
+
+# CLI-based engines (subprocess execution)
+bin/raictl compile --engine goose
+bin/raictl compile --engine aider
+
+# IDE-integrated engines
+bin/raictl compile --engine cursor
+bin/raictl compile --engine copilot
+bin/raictl compile --engine windsurf
+```
+
+### Engine Detection
+
+```bash
+# List all known engines
+bin/raictl engines list
+
+# Detect installed engines on the system
+bin/raictl engines detect
+
+# Show default engine and detection status
+bin/raictl engines status
+```
+
+### Quorum (Multi-Engine Analysis)
+
+```bash
+# Analyze rules across multiple engines
+bin/raictl adopt --api --quorum
+```
+
+## D-Bus and Desktop Commands
+
+Desktop features require the `rosett-ai-gtk4` package.
+
+### D-Bus Service
+
+```bash
+# Start the session bus service
+bin/raictl dbus start
+
+# Stop the service
+bin/raictl dbus stop
+```
+
+### GTK4 Desktop Application
+
+```bash
+# Launch the GTK4 desktop app
+bin/raictl desktop gtk4
+```
+
+## Adopt Commands
+
+Analyze compiled rule files for inconsistencies, conflicts, harmful content, duplicates, and other issues.
+
+### Analyze Rules
+
+```bash
+# Local-only structural checks (default)
+bin/raictl adopt
+
+# Verbose output with processing details
+bin/raictl adopt --verbose
+
+# Show detailed explanations for each finding
+bin/raictl adopt --elaborate
+
+# Enable remote API analysis
+bin/raictl adopt --api
+
+# Combined flags
+bin/raictl adopt --api --elaborate --verbose
+```
+
+### Flags
+
+| Flag | Effect |
+|------|--------|
+| `--api` | Enable remote API analysis (default: local only) |
+| `--verbose` | Show file counts, checksums, cache status, skipped files |
+| `--elaborate` | Add explanation column to findings table |
+| `--quorum` | Multi-engine analysis (requires `--api`) |
+
+### Environment Variables
+
+| Variable | Purpose | Default |
+|----------|---------|---------|
+| `ANTHROPIC_API_KEY` | API key for Claude analysis | (required for API mode) |
+| `ANTHROPIC_API_BASE_URL` | Custom API endpoint (Bedrock/Vertex/proxy) | `https://api.anthropic.com` |
+
+### Privacy Controls
+
+1. Mark behaviour files as `sensitive: true` to exclude from API analysis
+2. Configure redaction patterns in `conf/adopt_redactions.yml`
+3. Set `ANTHROPIC_API_BASE_URL` for private endpoints
+4. Omit `--api` flag to stay local-only (default)
+
+## Rake Tasks
+
+Alternative access via Rake:
+
+```bash
+# Update documentation
+bundle exec rake docs:update
+
+# Check documentation status
+bundle exec rake docs:status
+
+# Validate behaviours
+bundle exec rake behaviour:validate
+
+# List behaviours
+bundle exec rake behaviour:list
+```
+
+## Environment Variables
+
+| Variable | Purpose | Default |
+|----------|---------|---------|
+| `EDITOR` | Editor for behaviour files | `vim` |
+| `USER` | Default author for new behaviours | system user |
+| `ANTHROPIC_API_KEY` | API key for `adopt` command | (required for API mode) |
+| `ANTHROPIC_API_BASE_URL` | Custom API endpoint for `adopt` | `https://api.anthropic.com` |
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | Validation failed or command error |
+
+## Examples
+
+### Complete Workflow
+
+```bash
+# 1. Create a new behaviour
+bin/raictl behaviour manage add code_review --description="Code review guidelines"
+
+# 2. Edit the created file in $EDITOR
+# Add your rules...
+
+# 3. Validate the behaviour
+bin/raictl behaviour validate code_review
+
+# 4. View all behaviours
+bin/raictl behaviour display
+
+# 5. Update documentation
+bin/raictl documentation update
+```
+
+## Tooling Commands
+
+Validate CI/CD configuration files.
+
+### Validate GitLab CI YAML
+
+Validates all GitLab CI YAML files (`.gitlab-ci.yml` and `.gitlab-ci-files/**/*.yml`) for syntax errors. Uses AST-only parsing to accept GitLab CI custom tags like `!reference` while catching genuine syntax issues.
+
+```bash
+# Validate (errors only)
+bin/raictl tooling validate-ci-yaml
+
+# Validate with all file results
+bin/raictl tooling validate-ci-yaml --verbose
+
+# Validate a different project directory
+bin/raictl tooling validate-ci-yaml --project-dir=/path/to/project
+```
+
+### Flags
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--verbose` | `false` | Show all validated files, not just errors |
+| `--project-dir` | current directory | Project directory to scan |
+
+### CI/CD Integration
+
+```bash
+# In CI pipeline
+bin/raictl behaviour validate || exit 1
+bin/raictl tooling validate-ci-yaml || exit 1
+bundle exec rspec
+bundle exec rubocop
+```