rosett-ai 1.3.3

data/doc/CLAUDE_SESSIONS_MOVED.md

@@ -0,0 +1,16 @@
+# Claude Sessions Moved
+
+The Claude Code session transcripts and memory files that were previously stored in
+`doc/claude-sessions/` have been relocated to the workspace-level `.claude/` directory:
+
+| Previous Location | New Location |
+|-------------------|--------------|
+| `doc/claude-sessions/*.jsonl` | `~/git/Neatnerds/NNSD/NeatNerds-ai/.claude/sessions/rosett-ai-core/` |
+| `doc/claude-sessions/memory/` | `~/git/Neatnerds/NNSD/NeatNerds-ai/.claude/memory/` |
+| `settings.json` (repo root) | `~/git/Neatnerds/NNSD/NeatNerds-ai/.claude/settings.json` |
+
+This change was made on 2026-03-12 as part of the ecosystem orchestration overhaul
+to separate Claude-specific assets from engine-agnostic code.
+
+The original session archives (NNCO-era, 272MB) are preserved in:
+`~/Archives/claude-sessions/nnco-rosett-ai-sessions-20260312.tar.zst`

data/doc/COMMAND_ANALYSIS.md

@@ -0,0 +1,229 @@
+# Command Overlap & Friction Analysis
+
+**Date**: 2026-03-15
+**Scope**: All 18 registered CLI entry points (1 top-level + 17 subcommand groups)
+**Method**: Static analysis of `lib/rosett_ai/thor/cli.rb` and all `lib/rosett_ai/thor/tasks/*.rb`
+
+## Command Surface Summary
+
+| # | Group | Commands | Visibility | File |
+|---|-------|----------|------------|------|
+| 1 | `version` | 1 | public | `cli.rb:54` |
+| 2 | `compile` | 1 | public | `tasks/compile.rb` |
+| 3 | `validate` | 1 | public | `tasks/validate.rb` |
+| 4 | `adopt` | 1 | public | `tasks/adopt.rb` |
+| 5 | `init` | 1 | public | `tasks/init.rb` |
+| 6 | `backup` | 1 | public | `tasks/backup.rb` |
+| 7 | `behaviour` | 7 | public | `tasks/behaviour.rb` |
+| 8 | `build` | 2 | public | `tasks/build.rb` |
+| 9 | `design` | 3 | public | `tasks/design.rb` |
+| 10 | `config` | 2 | public | `tasks/config.rb` |
+| 11 | `tooling` | 3 | public | `tasks/tooling.rb` |
+| 12 | `license` | 3 | public | `tasks/license.rb` |
+| 13 | `content` | 3 | public | `tasks/content.rb` |
+| 14 | `engines` | 4 | public | `tasks/engines.rb` |
+| 15 | `release` | 3 | internal | `tasks/release.rb` |
+| 16 | `documentation` | 3 | internal | `tasks/documentation.rb` |
+| 17 | `dbus` | 4 | internal | `tasks/dbus.rb` |
+| 18 | `desktop` | 2 | internal | `tasks/desktop.rb` |
+| | **Total** | **~45** | 14 public / 4 internal | |
+
+## Finding 1: Validate Fragmentation (OVERLAP)
+
+**Severity**: Medium
+**Type**: DRY concern + discoverability
+
+Validation exists in four places:
+
+| Command | Scope | Accepts NAME arg? |
+|---------|-------|-------------------|
+| `rai validate` | All categories (behaviour + design + tooling) | No |
+| `rai behaviour validate [NAME]` | Behaviour files only | Yes (optional) |
+| `rai design validate [NAME]` | Design documents only | Yes (optional) |
+| `rai tooling validate [NAME]` | Tooling configs only | Yes (optional) |
+
+**Friction**: A user running `rai validate` gets the umbrella check, but cannot target a single file. The per-category commands allow targeting but require knowing which category a file belongs to.
+
+**Recommendation**: The current structure is defensible — `rai validate` is the CI/pre-commit entry point,
+per-category commands are for authoring workflows. No change needed, but consider adding
+`rai validate --category design` as a middle ground in a future iteration.
+
+## Finding 2: Compile Ambiguity (FRICTION)
+
+**Severity**: Medium
+**Type**: Naming collision
+
+Two unrelated "compile" operations exist:
+
+| Command | Input | Output | Purpose |
+|---------|-------|--------|---------|
+| `rai compile` | `conf/behaviour/*.yml` | `rules/*.md` | Compile behaviour rules to engine-native format |
+| `rai config compile` | `conf/claude_code/*.yml` | `settings.json` | Compile scope configs to Claude Code settings |
+
+**Friction**: "compile" means different things depending on context. A user who just installed rosett-ai and runs `rai compile` might expect it to compile *everything* (including config), or vice versa.
+
+**Recommendation**: This is a genuine UX concern. Two options:
+
+1. **Accept it**: Both are compile operations for different artefacts.
+   The subcommand nesting (`config compile`) disambiguates. Document clearly.
+2. **Unify**: Make `rai compile` the umbrella that compiles rules + config + locales,
+   add `--only rules` / `--only config` for targeting. This would be a breaking change.
+
+**Verdict**: Accept for v1.0.0. Document in help text. Revisit if user confusion is reported.
+
+## Finding 3: Tooling Validate Name Collision (FRICTION)
+
+**Severity**: Low
+**Type**: Naming ambiguity within a subcommand group
+
+| Command | Purpose |
+|---------|---------|
+| `rai tooling validate [NAME]` | Validate tooling YAML against schema |
+| `rai tooling validate-ci-yaml` | Validate GitLab CI YAML syntax |
+
+**Friction**: Both start with "validate" but do completely different things. A user running `rai tooling validate` might expect it to also validate CI YAML.
+
+**Recommendation**: Acceptable as-is. The schema validation checks *tooling config* structure, while `validate-ci-yaml` checks *CI pipeline* syntax. They are genuinely different. The kebab-case compound name `validate-ci-yaml` is distinct enough.
+
+## Finding 4: Provenance CLI Gap (MISSING)
+
+**Severity**: High
+**Type**: Documentation/implementation mismatch
+
+The `provenance` command is fully documented in CLAUDE.md (6 subcommands: `init`, `add`, `validate`, `show`, `log`) but **not implemented** in the CLI. No task file exists at `lib/rosett_ai/thor/tasks/provenance.rb`.
+
+The library module `RosettAi::Provenance::*` exists and is functional, but has no CLI exposure.
+
+**Documented commands without implementation**:
+
+- `rai provenance init`
+- `rai provenance add [--engine ENGINE]`
+- `rai provenance validate`
+- `rai provenance show COMMIT [--file PATH]`
+- `rai provenance log [--role ROLE]`
+
+**Recommendation**: Either implement the CLI commands or remove them from CLAUDE.md. Given that provenance
+is actively used (102 entries in `.ai-provenance.yml`), implementing the CLI is the right choice.
+This is a feature gap, not a friction issue.
+
+## Finding 5: Design vs Behaviour Feature Parity (GAP)
+
+**Severity**: Low
+**Type**: Asymmetric command surface
+
+| Operation | `behaviour` | `design` |
+|-----------|-------------|----------|
+| `list` | Yes | Yes |
+| `show NAME` | Yes | Yes |
+| `validate [NAME]` | Yes | Yes |
+| `display` (table) | Yes | No |
+| `manage add` | Yes | No |
+| `manage modify` | Yes | No |
+| `manage delete` | Yes | No |
+
+**Friction**: Behaviour files have full CRUD management; design documents are created/edited manually. A user might expect `rai design manage add` to scaffold a design doc.
+
+**Recommendation**: Acceptable asymmetry. Design documents are authored by humans and reviewed
+carefully — scaffolding would encourage boilerplate. Behaviour files have strict schema constraints
+that justify managed creation. If scaffolding is desired later, the `rosett-ai-dev-tools` gem already
+provides template generation.
+
+## Finding 6: Naming Consistency (MINOR)
+
+**Severity**: Low
+**Type**: Cosmetic
+
+| Pattern | Examples |
+|---------|----------|
+| Single-word commands | `compile`, `validate`, `adopt`, `init`, `backup` |
+| Kebab-case subcommands | `validate-ci-yaml`, `check-versions` |
+| Noun-based groups | `behaviour`, `design`, `config`, `tooling`, `engines` |
+| Verb-based groups | `compile`, `validate`, `adopt`, `build`, `backup` |
+
+**Observation**: Top-level commands mix verbs (`compile`, `validate`) with nouns (`behaviour`, `engines`). This is standard Thor/CLI convention — verbs for actions, nouns for resource management groups. No friction in practice.
+
+**Recommendation**: No change needed. Consistent within categories.
+
+## Finding 7: Engine Flag Duplication (MINOR)
+
+**Severity**: Low
+**Type**: Repeated option definition
+
+The `--engine` flag appears on:
+
+- `rai compile --engine NAME`
+- `rai config compile --engine NAME`
+- `rai config show --engine NAME`
+
+Each independently defaults to the configured default engine. This is correct (each command needs it), but the flag is defined separately in each task file.
+
+**Recommendation**: No change needed. Thor class_options don't propagate to subcommands, so duplication is necessary. A shared concern module could DRY this if more commands need it.
+
+## Finding 8: Internal Command Gating (OK)
+
+**Severity**: None
+**Type**: Design validation
+
+Four command groups are gated behind `RAI_INTERNAL=true`:
+
+- `release` — version bumping, tagging, changelog
+- `documentation` — doc generation, translation
+- `dbus` — D-Bus service lifecycle
+- `desktop` — GUI launcher
+
+**Assessment**: Correct gating. These are development/infrastructure commands that end users should not invoke. The gating mechanism (env var check + hidden from `--help`) is clean.
+
+## Finding 9: Missing `--verbose` Consistency (MINOR)
+
+**Severity**: Low
+**Type**: UX inconsistency
+
+| Command | Has `--verbose`? |
+|---------|-----------------|
+| `compile` | Yes |
+| `adopt` | Yes |
+| `config compile` | Yes |
+| `tooling validate-ci-yaml` | Yes |
+| `tooling check-versions` | Yes |
+| `build package` | Yes |
+| `build engine` | Yes |
+| `validate` | No |
+| `behaviour validate` | No |
+| `design validate` | No |
+| `init` | No |
+| `backup` | No |
+
+**Friction**: Validation commands don't have `--verbose`, so users cannot get detailed output when debugging schema failures.
+
+**Recommendation**: Consider adding `--verbose` to `validate`, `behaviour validate`, and `design validate` in a future iteration. Low priority — the current error messages include schema violation details.
+
+## KISS Assessment
+
+| Principle | Status | Notes |
+|-----------|--------|-------|
+| Command count | OK | 45 commands across 18 groups is moderate for a tool of this scope |
+| Nesting depth | OK | Maximum 3 levels (`build package execute`) — within Thor norms |
+| Option count | OK | No command has more than 7 options (build package = 7) |
+| Default behaviour | Good | `compile`, `adopt`, `init` all have sensible defaults |
+| Discoverability | Good | `--help` works at every level; internal commands hidden |
+| Naming | Good | Consistent within categories; no cryptic abbreviations |
+
+## Summary Matrix
+
+| # | Finding | Severity | Type | Action |
+|---|---------|----------|------|--------|
+| 1 | Validate fragmentation | Medium | Overlap | Accept; document |
+| 2 | Compile ambiguity | Medium | Friction | Accept for v1.0.0; document |
+| 3 | Tooling validate collision | Low | Friction | Accept |
+| 4 | Provenance CLI gap | High | Missing | Implement or remove from docs |
+| 5 | Design vs Behaviour parity | Low | Gap | Accept; asymmetry is intentional |
+| 6 | Naming consistency | Low | Cosmetic | No change |
+| 7 | Engine flag duplication | Low | DRY | No change (Thor limitation) |
+| 8 | Internal gating | None | OK | Validated correct |
+| 9 | Missing --verbose | Low | UX | Future iteration |
+
+## Actionable Items
+
+1. **Implement `provenance` CLI** (Finding 4) — or remove from CLAUDE.md
+2. **Document compile disambiguation** (Finding 2) — clarify in `--help` text
+3. **Consider `--verbose` on validate commands** (Finding 9) — future enhancement

data/doc/CONFIGURATION.md

@@ -0,0 +1,281 @@
+# Rosett-AI - Configuration Reference
+
+## Configuration Files
+
+### settings.json
+
+Global Claude Code settings. Version controlled.
+
+Location: `~/.claude/settings.json`
+
+```json
+{
+  "permissions": {
+    "allow": [],
+    "deny": [],
+    "additionalDirectories": []
+  }
+}
+```
+
+### settings.local.json
+
+Local overrides. Gitignored for machine-specific settings.
+
+Location: `~/.claude/settings.local.json`
+
+### CLAUDE.md
+
+Global instructions for Claude Code. Markdown format.
+
+Location: `~/.claude/CLAUDE.md`
+
+## Permission Configuration
+
+### Allow Rules
+
+Permit specific operations:
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "Bash(rbenv versions:*)",
+      "Bash(bundle:*)",
+      "Bash(gem:*)",
+      "Bash(bin/raictl:*)"
+    ]
+  }
+}
+```
+
+### Deny Rules
+
+Block access to sensitive paths:
+
+```json
+{
+  "permissions": {
+    "deny": [
+      "Read(/home/user/.ssh/**)",
+      "Read(/home/user/.gnupg/**)",
+      "Read(/home/user/**/.env)",
+      "Read(/home/user/**/.env.*)",
+      "Read(/home/user/**/secrets/**)",
+      "Read(/home/user/**/*.pem)",
+      "Read(/home/user/**/*.key)"
+    ]
+  }
+}
+```
+
+### Additional Directories
+
+Grant Claude Code access to specific directories:
+
+```json
+{
+  "permissions": {
+    "additionalDirectories": [
+      "/home/user/projects",
+      "/var/log/myapp"
+    ]
+  }
+}
+```
+
+## Configuration Hierarchy
+
+Settings are merged in this order (later overrides earlier):
+
+1. `settings.json` (base)
+2. `settings.local.json` (local overrides)
+3. Group-level CLAUDE.md
+4. Project-level CLAUDE.md
+
+### Merge Behavior
+
+| Type | Behavior |
+|------|----------|
+| Objects | Deep merge |
+| Arrays | Union (deduplicated) |
+| Scalars | Override |
+
+## .claudeignore
+
+Patterns for files Claude should not access.
+
+Location: `~/.claude/.claudeignore`
+
+```gitignore
+# Credentials
+.credentials.json
+**/.env
+**/*.pem
+**/*.key
+
+# Runtime data
+history.jsonl
+cache/
+debug/
+```
+
+## Behaviour Files
+
+YAML configuration files in `conf/behaviour/`.
+
+### Schema
+
+```yaml
+name: string (required)
+description: string (required)
+version: string (semver format)
+author: string
+created_at: date
+modified_at: date
+modified_by: string
+sensitive: boolean          # exclude from API analysis during adopt
+used_in: array of strings
+rules: array (required, min 1 item)
+  - id: string (required)
+    description: string (required)
+    priority: integer (1-100)
+    enabled: boolean
+```
+
+### Example
+
+```yaml
+name: code_review
+description: Rules for code review assistance
+version: 1.0.0
+author: developer@neatnerds.be
+created_at: "2025-01-17"
+modified_at: "2025-01-17"
+modified_by: developer@neatnerds.be
+used_in:
+  - project_alpha
+  - project_beta
+rules:
+  - id: review_security
+    description: Always check for security vulnerabilities
+    priority: 90
+    enabled: true
+  - id: review_tests
+    description: Verify test coverage for changes
+    priority: 80
+    enabled: true
+```
+
+### Adopt Redactions
+
+Redaction patterns for the `adopt` command, stored in `conf/adopt_redactions.yml`:
+
+```yaml
+---
+patterns:
+  - pattern: '\b[A-Z0-9._%+-]+@neatnerds\.be\b'
+    replacement: '[EMAIL-REDACTED]'
+  - pattern: 'NeatNerds'
+    replacement: '[COMPANY]'
+```
+
+Patterns are applied to file contents before sending to the Claude API. Original files are never modified.
+
+### Adopt Cache
+
+Analysis results are cached in `conf/adopt.cache.yml`, keyed on the SHA256 of all analyzed file contents. Delete this file to force a fresh analysis.
+
+## Environment-Specific Configuration
+
+### Development
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "Bash(bundle exec:*)",
+      "Bash(bin/raictl:*)"
+    ]
+  }
+}
+```
+
+### Production
+
+More restrictive permissions for production environments:
+
+```json
+{
+  "permissions": {
+    "allow": [],
+    "deny": [
+      "Bash(*)",
+      "Write(*)"
+    ]
+  }
+}
+```
+
+## Project-Level Configuration
+
+### `.rosett-ai/config.yml`
+
+Created by `rai init --project`. Contains per-project settings:
+
+```yaml
+project_name: my-project
+default_engine: claude
+```
+
+When rosett-ai detects a `.rosett-ai/` directory (by walking up from the current directory), it resolves behaviour and design files from `.rosett-ai/conf/` instead of the global installation.
+
+### Engine Management
+
+Engines are installed as separate packages:
+
+```bash
+apt install rosett-ai-engine-claude
+apt install rosett-ai-engine-generic
+```
+
+Configure the default engine globally:
+
+```bash
+# In ~/.config/rosett-ai/config.yml
+default_engine: claude
+```
+
+Or per-project in `.rosett-ai/config.yml`, or per-command with `--engine`:
+
+```bash
+rai compile --engine generic
+```
+
+### Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `RAI_ORIGINAL_PWD` | Preserves working directory (set by `.deb` wrapper) |
+| `RAI_ENGINE_PATH` | Custom engine discovery paths (colon-separated) |
+| `RAI_LOG_LEVEL` | Log verbosity (`DEBUG`, `INFO`, `WARN`, `ERROR`) |
+
+## Validation
+
+Validate configuration files:
+
+```bash
+# Validate all config files
+bin/raictl validate
+
+# Validate behaviour files only
+bin/raictl behaviour validate
+
+# Validate design documents only
+bin/raictl design validate
+```
+
+## Further Reading
+
+- [REFERENCE.md](REFERENCE.md) - Complete CLI options and file locations reference
+- [INSTALL.md](../INSTALL.md) - Installation guide