rosett-ai 1.3.3

data/doc/man/rai.1.ronn

@@ -0,0 +1,505 @@
+nncc(1) -- NeatNerds Code Companion
+======================================
+
+## NAME
+
+`nncc` - configuration management tool for AI-assisted development workflows
+
+## SYNOPSIS
+
+`nncc` [--accessible] [--locale <locale>] [--ui <adapter>] <command> [<args>]
+
+## DESCRIPTION
+
+**nncc** is a configuration management tool for AI-assisted development workflows.
+It compiles YAML behaviour definitions into rule files for multiple AI engines, manages
+design documents, validates configurations, and builds Debian packages.
+
+raictl follows a security-first design with YAML safe loading, array-form shell
+commands, and whitelisted file paths. All configurations are versioned and
+validated against JSON Schema.
+
+## COMMANDS
+
+### Core Commands
+
+  * `version`:
+    Display the current nncc version and build information.
+
+  * `tree`:
+    Print a tree of all available commands with descriptions.
+
+  * `compile` [--verbose] [--simulate] [--vendor] [--engine <name>] [--strict] [--locales]:
+    Compile YAML behaviour configurations into markdown rule files. Use
+    `--simulate` for a dry run with diffs. Use `--vendor` to write a lockfile.
+    Use `--engine` to select the target engine (default: from config). Use
+    `--strict` to treat warnings as errors. Use `--locales` to compile locale
+    files to gettext and Qt formats. Available engines: `claude`
+    (default), `generic`, `agents_md`, `ollama`, `gpt_neox`, `goose`,
+    `aider`, `cursor`, `copilot`, `windsurf`.
+
+  * `validate`:
+    Validate all configuration files (behaviour, design, tooling) against
+    their respective JSON schemas. Reports per-category pass/fail counts
+    in a summary table.
+
+  * `init` --global|--local|--project [--no-compile]:
+    Initialize nncc directory structure. Use `--global` for ~/.claude/,
+    `--local` for project-level .claude/ structure, and `--project` to create
+    an `.nncc/` project structure with `config.yml` and conf subdirectories.
+    Engine detection runs automatically during init. Use `--no-compile` to
+    skip the rule compilation step.
+
+### Configuration Management
+
+  * `behaviour` display [--format table|json|yaml]:
+    Show current behaviour configuration as a table, JSON, or YAML.
+
+  * `behaviour` list:
+    List all behaviour files found in `conf/behaviour/`.
+
+  * `behaviour` show <name>:
+    Show details of a specific behaviour file including rules and metadata.
+
+  * `behaviour` validate [<name>]:
+    Validate behaviour file(s) against the behaviour schema. Validates all
+    files if no name is given, or a single file if <name> is specified.
+
+  * `behaviour` manage add <name> [--description <text>] [--author <name>]:
+    Create a new behaviour configuration file with a template structure.
+
+  * `behaviour` manage modify <name>:
+    Modify an existing behaviour file interactively.
+
+  * `behaviour` manage delete <name> [--force]:
+    Delete a behaviour file. Warns if the behaviour is referenced elsewhere.
+    Use `--force` to skip the confirmation prompt.
+
+  * `design` list:
+    List all design documents with name, version, status, domain, and priority.
+
+  * `design` show <name> [--full]:
+    Show a design document summary. Use `--full` to display intent,
+    constraints, acceptance criteria, examples, and anti-patterns.
+
+  * `design` validate [<name>]:
+    Validate design document(s) against the design schema.
+
+  * `config` show [--raw] [--engine <name>]:
+    Display compiled configuration for a scope with secrets masked.
+    Use `--raw` to show unmasked values.
+
+  * `config` compile [--verbose] [--simulate] [--scope <name>] [--engine <name>]:
+    Compile engine configuration YAML to native settings files (e.g.,
+    `settings.json` for Claude Code). Use `--scope` to compile a single scope
+    (managed, user, project, local). Use `--engine` to override the default
+    engine.
+
+### Operations
+
+  * `adopt` [--verbose] [--elaborate] [--api] [--quorum]:
+    Analyze compiled rule files for issues. Defaults to local-only structural
+    checks. Use `--api` to enable remote API analysis via the configured engine.
+    Use `--quorum` for multi-engine consensus analysis. Use `--elaborate` for
+    detailed findings.
+
+  * `engines` list:
+    List all known engines from the built-in manifest and plugin registry.
+
+  * `engines` detect:
+    Probe the system for installed engines (checks binaries, gems, configs).
+
+  * `engines` status:
+    Show the default engine and detection results for all engines.
+
+  * `engines` plugins:
+    Show registered plugin engines from the gem path.
+
+  * `backup` --global|--local [--compression <type>] [--compression-ratio <n>] [--destination <uri>]:
+    Back up nncc directory structure and assets. At least one of `--global`
+    or `--local` must be specified. Compression types: `zip` (default),
+    `tar.gz`, `tar.zst`. The `--destination` flag accepts `file://` URIs.
+
+  * `build` package [--verbose] [--clean] [--architecture <arch>] [--variant <name>] [--ruby-version <ver>] [--output-dir <dir>]:
+    Build a Debian `.deb` package using fpm and ruby-build. Available
+    variants: `core` (default), `gtk4`, `qt6`. The `--clean` flag removes
+    the staging directory before building. Internal command: only available
+    inside the rosett-ai repository.
+
+  * `build` engine [--verbose] [--path <dir>] [--output-dir <dir>] [--nncc-min-version <ver>]:
+    Build a `.deb` package for an rosett-ai engine plugin. Run from an engine
+    directory or specify `--path`. Sets minimum nncc version dependency
+    with `--nncc-min-version`.
+
+  * `tooling` validate-ci-yaml [--verbose]:
+    Validate GitLab CI YAML files for syntax errors. Checks `.gitlab-ci.yml`
+    and all included CI files.
+
+  * `tooling` validate [<name>]:
+    Validate tooling configuration files against the tooling schema.
+
+  * `tooling` check-versions [--verbose] [--gems]:
+    Check Ruby and gem version consistency across the codebase. Use `--gems`
+    to include gem version analysis.
+
+  * `dbus` status:
+    Show whether the `be.neatnerds.rosettai` D-Bus session service is running.
+
+  * `dbus` start [--daemonize]:
+    Start the D-Bus service with focus monitoring. Runs in the foreground
+    by default. Use `--daemonize` (`-d`) to run in the background.
+    Requires the `nncc-gtk4` package.
+
+  * `dbus` stop:
+    Send a shutdown signal to the running D-Bus service.
+
+  * `dbus` detect:
+    Detect the running compositor and show the selected focus adapter.
+
+  * `desktop` gtk4:
+    Launch the GTK4/Adwaita desktop application. Connects to the D-Bus
+    service for compile, status, and preference management. Requires the
+    `nncc-gtk4` package.
+
+  * `desktop` status:
+    Show desktop integration status (GTK4 availability, D-Bus service state).
+
+  * `documentation` update [--locale <locale>] [--all-locales] [--dry-run] [--skip-reference]:
+    Scan for documentation changes and apply updates. Detects undocumented
+    public methods, new behaviour files, and dependency changes. Use
+    `--skip-reference` to skip LaTeX reference compilation.
+
+  * `documentation` status:
+    Show documentation file count, modification dates, and configured locales.
+
+  * `documentation` translate [<file>] --to <locale> [--from <locale>]:
+    Translate documentation files to a target locale.
+
+### Compliance & Quality
+
+  * `comply` [--cra] [--license] [--headers] [--format table|json]:
+    Run compliance checks against project policies. Use `--cra` for
+    EU Cyber Resilience Act checks. Use `--license` for license
+    compatibility checks. Use `--headers` for SPDX header validation.
+
+  * `doctor` [--check <name>] [--format table|json]:
+    Run diagnostic checks on the nncc installation. Checks Ruby version,
+    gem dependencies, file permissions, D-Bus availability, engine
+    detection, and cache health. Use `--check` to run a single check.
+
+### Workflow & Project Management
+
+  * `workflow` list:
+    List available workflow definition files.
+
+  * `workflow` validate <name>:
+    Validate a workflow definition against the workflow schema.
+
+  * `workflow` simulate <name>:
+    Dry-run a workflow showing all steps without executing them.
+
+  * `workflow` execute <name> [--resume] [--format table|json]:
+    Execute a named workflow. Use `--resume` to continue from the last
+    successful step after a failure.
+
+  * `project` status [--format table|json]:
+    Show project status including health checks, engine, and configuration.
+
+  * `project` info:
+    Show project metadata (name, engine, template, behaviour/design counts).
+
+  * `project` apply-template <name> [--force] [--list]:
+    Apply a project template. Use `--list` to show available templates
+    without applying. Use `--force` to overwrite existing files.
+
+  * `project` drift [--type forward|template] [--format table|json]:
+    Detect configuration drift from the upstream template or from the
+    expected forward state.
+
+  * `project` sync [--force] [--simulate]:
+    Synchronize local configuration with upstream template updates.
+    Use `--simulate` for a dry run.
+
+### Integration
+
+  * `mcp` serve:
+    Start nncc as an MCP (Model Context Protocol) server on stdio transport.
+
+  * `mcp` list [--format table|json]:
+    List configured MCP servers.
+
+  * `mcp` validate [--format table|json]:
+    Validate MCP server configurations against the schema.
+
+  * `mcp` status [--format table|json]:
+    Show MCP server health status.
+
+  * `mcp` audit [--format table|json]:
+    Generate an MCP compliance audit report.
+
+  * `mcp` add <name> [--transport stdio|http|streamable-http]:
+    Install an MCP server from a trusted source.
+
+  * `mcp` remove <name> [--force]:
+    Remove a configured MCP server.
+
+  * `mcp` trust-sources [--format table|json]:
+    List configured trust sources for MCP server installation.
+
+  * `mcp` trust-add <domain> [--description <text>]:
+    Add a trusted domain for MCP server installation.
+
+  * `mcp` trust-remove <domain>:
+    Remove a trusted domain.
+
+  * `mcp` tools:
+    List available MCP tools from all configured servers.
+
+  * `hooks` install [--verbose]:
+    Install configured git hooks from `.nncc/config.yml`. Hooks are
+    defined in the project configuration and installed via the detected
+    hook manager (overcommit, husky, lefthook).
+
+  * `hooks` uninstall:
+    Remove nncc hooks and restore previous hooks.
+
+  * `hooks` list [--format table|json]:
+    Show installed nncc hooks.
+
+  * `hooks` status [--format table|json]:
+    Show hook installation status and detect drift from configuration.
+
+  * `plugins` list <type>:
+    List installed plugins of a given type. Valid types: `engine`, `gui`,
+    `mcp`.
+
+  * `plugins` install <type> <name>:
+    Install a plugin package (e.g., `plugins install engine ollama`).
+
+  * `plugins` remove <type> <name>:
+    Remove a plugin package.
+
+  * `retrofit` convert [--engine <name>...] [--force] [--simulate]:
+    Import native AI tool configurations into nncc YAML format. Reads
+    existing Claude Code, Cursor, or other tool configs and generates
+    equivalent nncc behaviour files. Use `--simulate` for a dry run.
+    Native files are never modified. This is the default subcommand.
+
+  * `retrofit` engines:
+    List available retrofit engine adapters.
+
+  * `completion` bash|zsh|fish:
+    Generate a shell completion script for the specified shell.
+    Output is written to stdout for piping.
+
+  * `completion` install [--shell <name>]:
+    Install the completion script to the standard system directory.
+    Auto-detects the current shell from `$SHELL` if `--shell` is not given.
+
+### AI Provenance
+
+  * `provenance` init:
+    Create `.ai-provenance.yml` in the current project root.
+
+  * `provenance` validate:
+    Validate all provenance entries and hash chain integrity.
+
+  * `provenance` show <commit> [--file <path>]:
+    Show provenance for a specific commit or all entries referencing a file.
+
+  * `provenance` log [--role <role>]:
+    Show all provenance entries in reverse chronological order. Filter by
+    AI role with `--role` (e.g., `AI-Co-Author`, `AI-Generated-By`).
+
+### Release Management
+
+  * `release` prepare <level> [--skip-verify]:
+    Prepare a release. Bumps version (major, minor, or patch), runs the
+    verification suite, generates CHANGELOG entries via git-cliff, and
+    creates a release commit. The `--skip-verify` flag skips the quality
+    gate suite (NOT recommended).
+
+  * `release` tag:
+    Create an annotated git tag from the current VERSION constant.
+
+  * `release` status:
+    Show current version, last tag, and number of unreleased commits.
+
+### Licensing
+
+  * `license` activate <key>:
+    Activate a license key for premium content pack access. The key is
+    verified using Ed25519 signature validation. Licenses control content
+    access only, never software functionality (GPL-3.0).
+
+  * `license` status:
+    Show current license status including tier and validity.
+
+  * `license` deactivate:
+    Remove the license key and revert to Community tier.
+
+  * `content` list [--available]:
+    Show installed content packs. Use `--available` to also show packs
+    available for download.
+
+  * `content` install <name>:
+    Download, verify signature, and install a content pack.
+
+  * `content` update:
+    Re-download all installed content packs (requires subscriber tier).
+
+## GLOBAL OPTIONS
+
+  * `--accessible`:
+    Enable accessible output mode (screen-reader friendly tables, ARIA
+    live regions, EN 301 549 compliant).
+
+  * `--locale`=<locale>:
+    Display output in specified locale (e.g., `en`, `fr`, `ar`).
+    Arabic locale uses right-to-left rendering.
+
+  * `--ui`=<adapter>:
+    UI adapter to use. One of: `tui` (default), `gtk4`, `qt6`, `kde`.
+
+## FILES
+
+  * `~/.config/nncc/config.yml`:
+    raictl runtime configuration (default engine, cache settings, detection).
+
+  * `~/.claude/`:
+    Global Claude Code configuration directory.
+
+  * `~/.claude/conf/behaviour/*.yml`:
+    Behaviour configuration files defining Claude operational rules.
+
+  * `~/.claude/conf/design/*.yml`:
+    Design documents specifying implementation standards.
+
+  * `~/.claude/conf/schemas/*.json`:
+    JSON Schema files for configuration validation.
+
+  * `~/.claude/rules/`:
+    Compiled rule files (generated by `nncc compile`).
+
+  * `~/.claude/settings.json`:
+    Global Claude Code settings.
+
+  * `.nncc/config.yml`:
+    Per-project configuration (project name, default engine, hooks).
+
+  * `.nncc/conf/behaviour/*.yml`:
+    Project-specific behaviour overrides.
+
+  * `.ai-provenance.yml`:
+    AI provenance tracking file (created by `nncc provenance init`).
+
+  * `/etc/nncc/settings.json`:
+    System-wide default settings (installed by .deb package).
+
+## EXIT STATUS
+
+  * `0`:
+    Success.
+
+  * `1`:
+    General error (validation failure, missing file, invalid argument).
+
+  * `2`:
+    Validation error (schema mismatch, invalid YAML).
+
+  * `3`:
+    Configuration error (missing scope, bad engine name).
+
+  * `4`:
+    Permission error (read-only directory, denied path).
+
+  * `5`:
+    Dependency error (missing gem, unavailable engine).
+
+## ENVIRONMENT
+
+  * `XDG_CONFIG_HOME`:
+    Base directory for nncc configuration (default: `~/.config`).
+    raictl stores its own config at `$XDG_CONFIG_HOME/nncc/config.yml`.
+
+  * `LANG`, `LC_ALL`:
+    Used for locale resolution when `--locale` is not specified.
+
+  * `NO_COLOR`:
+    When set, disables colour output (see https://no-color.org/).
+
+  * `RAI_TELEMETRY`:
+    Set to `1` to enable structured JSON Lines telemetry to stderr.
+
+  * `RAI_PROFILE`:
+    Set to `1` to print per-phase timing breakdown to stderr.
+
+  * `RAI_ENGINE_PATH`:
+    Colon-separated list of additional directories to search for engine
+    plugin gems.
+
+  * `RAI_LOG_LEVEL`:
+    Log verbosity. One of: `DEBUG`, `INFO`, `WARN`, `ERROR`.
+
+  * `RAI_LICENSE_KEY`:
+    License key for premium content pack access (alternative to
+    `license activate`).
+
+  * `RAI_ORIGINAL_PWD`:
+    Preserves the user's working directory when invoked via the `.deb`
+    wrapper script. Set automatically; do not override.
+
+  * `DBUS_SESSION_BUS_ADDRESS`:
+    D-Bus session bus address. Required for `dbus` and `desktop` commands.
+
+## EXAMPLES
+
+Compile rules for the default engine:
+
+    $ nncc compile --verbose
+
+Dry-run compilation for Cursor engine:
+
+    $ nncc compile --engine cursor --simulate --verbose
+
+Validate all configuration files:
+
+    $ nncc validate
+
+Initialize a new project:
+
+    $ cd my-project && nncc init --project
+
+Run diagnostic checks:
+
+    $ nncc doctor
+
+Check compliance:
+
+    $ nncc comply --cra --license --headers
+
+Generate bash completion:
+
+    $ nncc completion bash > /usr/share/bash-completion/completions/nncc
+
+Import existing Claude Code config:
+
+    $ nncc retrofit --engine claude --simulate
+
+Start MCP server:
+
+    $ nncc mcp serve
+
+## SEE ALSO
+
+claude(1), git-cliff(1), rubocop(1), ronn-ng(1)
+
+Project repository: <https://gitlab.neatnerds.be/neatnerds/nncc>
+
+## AUTHORS
+
+Hugo Antonio Sepulveda Manriquez <hugo@neatnerds.be>
+
+## LICENSE
+
+GPL-3.0-only. See the LICENSE file in the project repository.

data/doc/operations/packaging.md

@@ -0,0 +1,133 @@
+# Packaging Operations
+
+How to build, verify, and install the Rosett-AI `.deb` package.
+
+## Building the .deb
+
+Prerequisites: `fakeroot`, `dpkg-deb`, `rsync`, `ruby-build`, `fpm`.
+
+```bash
+# Standard build (reuses cached Ruby if already compiled)
+bundle exec raictl build package --verbose
+
+# Clean build (recompiles Ruby from source)
+bundle exec raictl build package --clean --verbose
+
+# Build a specific variant
+bundle exec raictl build package --variant gtk4 --verbose
+```
+
+Output lands in `pkg/rosett-ai_<version>-<iteration>_<arch>.deb`.
+
+## Hermetic Path Guarantee
+
+The build system ensures **no workstation-specific paths** leak into the package:
+
+1. **`embedded_env`** uses a hardcoded `HERMETIC_SYSTEM_PATH`
+   (`/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin`)
+   instead of inheriting the builder's `$PATH`.
+
+2. **`APP_EXCLUDES`** strips developer-only directories (`.claude`,
+   `doc/claude-sessions`, `.git`, `spec`, `coverage`, etc.) from the
+   application source during rsync.
+
+3. **`clean_build_artifacts!`** removes native gem build debris
+   (`gem_make.out`, `mkmf.log`, `Makefile` in `ext/` directories) that
+   embed the build host's staging path. These files are not needed at
+   runtime.
+
+4. **BUNDLE_DEPLOYMENT=true** with a relative `vendor/bundle` path
+   ensures the `.bundle/config` inside the package is portable.
+
+## Verifying Hermetic Paths
+
+After building, extract the package and check for leaked paths:
+
+```bash
+# Extract without installing
+mkdir /tmp/deb-check
+dpkg-deb --fsys-tarfile pkg/rosett-ai_*.deb | tar xf - -C /tmp/deb-check
+
+# Check for /home/ paths in text files (excluding binary .so and .ri)
+grep -rl '/home/' /tmp/deb-check/opt/rosett-ai/app/ \
+  | grep -v '\.so$' | grep -v '\.ri$'
+
+# Expected: only documentation files with example paths (SETUP.md, etc.)
+# Unexpected: gem_make.out, mkmf.log, Makefile, .bundle/config
+
+# Verify the wrapper script
+grep '/home/' /tmp/deb-check/opt/rosett-ai/bin/raictl
+# Expected: no output
+
+# Verify .bundle/config uses relative paths
+cat /tmp/deb-check/opt/rosett-ai/app/.bundle/config
+# Expected: BUNDLE_PATH: "vendor/bundle" (relative, not absolute)
+
+# Verify no .claude or session dirs shipped
+ls /tmp/deb-check/opt/rosett-ai/app/.claude/ 2>&1
+ls /tmp/deb-check/opt/rosett-ai/app/doc/claude-sessions/ 2>&1
+# Expected: "No such file or directory" for both
+```
+
+## Installing on a Clean System
+
+```bash
+sudo dpkg -i pkg/rosett-ai_1.2.0-1_amd64.deb
+
+# Verify installation
+raictl version           # Should print 1.2.0
+raictl compile --verbose # Should compile without errors
+```
+
+The package installs to:
+
+| Path | Contents |
+|------|----------|
+| `/opt/rosett-ai/embedded/` | Self-contained Ruby 3.3.10 runtime |
+| `/opt/rosett-ai/app/` | Application source and vendored gems |
+| `/opt/rosett-ai/bin/raictl` | Runtime wrapper script |
+| `/opt/rosett-ai/etc/` | Default settings and BUILD_INFO |
+| `/etc/rosett-ai/settings.json` | User-editable conffile |
+| `/usr/local/bin/raictl` | Symlink (created by postinst) |
+| `/usr/local/bin/rai` | Symlink (created by postinst) |
+| `/usr/share/man/man1/rai.1.gz` | Man page |
+
+## Troubleshooting
+
+### `raictl: command not found`
+
+The postinst script creates symlinks at `/usr/local/bin/`. If these are
+missing, recreate manually:
+
+```bash
+sudo ln -sf /opt/rosett-ai/bin/raictl /usr/local/bin/raictl
+sudo ln -sf /opt/rosett-ai/bin/raictl /usr/local/bin/rai
+```
+
+### `cannot load such file -- bundler/setup`
+
+The embedded Ruby cannot find its gems. Check:
+
+```bash
+# Verify BUNDLE_PATH in the wrapper
+grep BUNDLE_PATH /opt/rosett-ai/bin/raictl
+# Should be: /opt/rosett-ai/app/vendor/bundle
+
+# Verify gems are installed
+ls /opt/rosett-ai/app/vendor/bundle/ruby/*/gems/ | head -5
+```
+
+### `libruby.so.3.3: cannot open shared object file`
+
+The embedded `LD_LIBRARY_PATH` isn't being set. Verify the wrapper
+script sets it to `/opt/rosett-ai/embedded/lib`.
+
+### Workstation paths in package (build regression)
+
+If `grep -r '/home/' /opt/rosett-ai/` finds paths outside documentation,
+the hermetic build guarantee has regressed. Check:
+
+1. `embedded_env` in `lib/rosett_ai/thor/tasks/build.rb` — must use
+   `HERMETIC_SYSTEM_PATH`, not `ENV.fetch('PATH')`
+2. `clean_build_artifacts!` stage — must run after `install_gems!`
+3. `APP_EXCLUDES` — must include `.claude` and `doc/claude-sessions`

data/doc/operations/rosett-ai-release.md

@@ -0,0 +1,65 @@
+# Rosett-AI Release Procedure
+
+## Prerequisites
+
+- All tests pass: `bundle exec rspec`
+- RuboCop clean: `bundle exec rubocop`
+- No security vulnerabilities: `bundle exec bundler-audit check`
+- Branch is up to date with main
+
+## Steps
+
+### 1. Version bump
+
+```bash
+# Option A: Use raictl release
+bin/raictl release prepare minor   # or patch, major
+
+# Option B: Manual
+# Edit lib/rosett_ai/version.rb
+# Update CHANGELOG.md
+```
+
+### 2. Verify
+
+```bash
+bin/raictl version                        # Confirm new version
+bin/raictl release status                 # Check commit count since last tag
+bundle exec rspec                         # Full test suite
+bin/raictl compile --verbose              # Claude engine compiles
+bin/raictl compile --engine agents_md --verbose  # AGENTS.md engine compiles
+```
+
+### 3. Commit and push
+
+```bash
+git add lib/rosett_ai/version.rb CHANGELOG.md
+git commit -m "chore(release): bump version to X.Y.Z"
+git push -u origin <branch>
+```
+
+### 4. Create merge request
+
+```bash
+glab mr create --title "chore(release): vX.Y.Z" --description "Release X.Y.Z"
+```
+
+### 5. After merge: tag
+
+```bash
+git checkout main && git pull
+bin/raictl release tag    # Creates annotated tag vX.Y.Z
+git push --tags
+```
+
+### 6. Build .deb package (optional)
+
+```bash
+bin/raictl build package --clean --verbose
+# Output: pkg/rosett-ai_X.Y.Z_amd64.deb
+```
+
+### 7. Post-release
+
+- Update OpenProject work packages to "Closed"
+- Verify installed package: `raictl version`