chore: prepare v2.3.0 release

.planning/MILESTONES.md

@@ -1,5 +1,31 @@
 # Project Milestones: RuleZ (AI Policy Engine)
 
+## v2.2.2 Documentation Audit & Multi-CLI Guides (Shipped: 2026-03-17)
+
+**Delivered:** Complete documentation overhaul — all reference docs audited against source code, per-CLI usage guides created, and new feature documentation for external logging, lint, and test.
+
+**Phases completed:** 30-33 (8 plans total)
+
+**Key accomplishments:**
+
+- Accurate CLI reference for all 14 rulez commands with flags verified against --help output
+- Complete hooks-yaml-schema.md with parallel eval, config caching, globset, and external logging fields
+- Quick-reference.md updated with all 22 CLI commands, action types, and exit codes
+- End-to-end usage guides for Claude Code, Gemini CLI, and OpenCode
+- Tutorial-first feature documentation for external logging (OTLP, Datadog, Splunk), lint (9 rules), and test
+- 13 docs audited with `last_validated` frontmatter for audit trail
+
+**Stats:**
+
+- 4 phases, 8 plans
+- 42 files changed, 5,856 insertions, 521 deletions
+- 36 commits over 3 days (2026-03-14 → 2026-03-16)
+- Requirements: 11/11 satisfied
+
+**Git range:** `1c86551` → `2339853`
+
+---
+
 ## v2.2.1 Cleanup, Sync Skills, CLI Help & UI Integration (Shipped: 2026-03-13)
 
 **Phases completed:** 29 phases, 79 plans, 8 tasks

.planning/PROJECT.md

@@ -32,7 +32,7 @@ RuleZ positions itself as comparable to:
 
 ## Current State
 
-### RuleZ Core (v2.2.1)
+### RuleZ Core (v2.2.2)
 - Policy engine with blocking, injection, validation, inline scripting, schema validation
 - CLI: init, install, uninstall, validate, logs, explain, debug, repl, test, lint, upgrade
 - Multi-CLI support: Claude Code, Gemini, Copilot, OpenCode (install/doctor commands)
@@ -84,11 +84,48 @@ RuleZ positions itself as comparable to:
 - ✓ REQ-PERF-01..02: Performance quality gates (<0.1ms schema validation) — v1.4
 - ✓ REQ-COMPAT-01..02: Cross-platform compatibility (CI matrix) — v1.4
 
-### Active
+- ✓ CLIDOC-01..03: CLI reference docs updated with all commands and flags — v2.2.2
+- ✓ GUIDE-01..03: Per-CLI usage guides (Claude Code, Gemini, OpenCode) — v2.2.2
+- ✓ FEAT-01..03: Feature documentation (external logging, lint, test) — v2.2.2
+- ✓ AUDIT-01..02: Accuracy audit against source code and --help output — v2.2.2
 
-(No active requirements — planning next milestone)
+### Active
 
-See REQUIREMENTS.md for next milestone requirements when defined.
+- [ ] PROFILE-01: Runtime profiles define per-platform conventions (dirs, separators, tool style)
+- [ ] PROFILE-02: Skill discovery scans .claude/skills/, .claude/commands/, and extra dirs
+- [ ] PROFILE-03: Extra skill sources (mastering-hooks at repo root) discovered automatically
+- [ ] XFORM-01: Tool names converted from PascalCase to runtime conventions
+- [ ] XFORM-02: Path references rewritten (~/.claude/ -> runtime equivalents)
+- [ ] XFORM-03: Command filenames flattened (dot to hyphen) with cross-reference rewriting
+- [ ] XFORM-04: YAML frontmatter converted (allowed-tools -> tools, color hex, strip unsupported)
+- [ ] XFORM-05: MCP tools excluded for Gemini, preserved for OpenCode
+- [ ] CLI-01: `rulez skills install --runtime <rt>` installs to target runtime
+- [ ] CLI-02: `rulez skills install --dry-run` previews without writing
+- [ ] CLI-03: `rulez skills clean --runtime <rt>` removes generated files
+- [ ] CONFIG-01: Auto-update GEMINI.md skill registry with marker sections
+- [ ] CONFIG-02: Auto-generate AGENTS.md for Codex with skill registry
+- [ ] CONFIG-03: Mastering-hooks platform references rewritten context-aware
+- [ ] DX-01: `rulez skills status` shows human-readable dates and freshness
+- [ ] DX-02: `rulez skills diff --runtime <rt>` shows colored diff of changes
+- [ ] DX-03: `rulez skills sync` installs to all detected runtimes
+- [ ] DX-04: Colorized output with progress indicators
+
+## Current Milestone: v2.3.0 Multi-Runtime Skill Portability
+
+**Goal:** Build an installer-based conversion pipeline that transforms canonical Claude Code skills into runtime-specific installations. Author once in `.claude/`, convert at install time, run everywhere.
+
+**Target features:**
+- Runtime profiles and skill discovery (Phase 34 — DONE)
+- Content transformation engine with 6 transform types (Phase 35 — DONE)
+- CLI integration with file writer (Phase 36 — DONE)
+- Config file generation for GEMINI.md, AGENTS.md (Phase 37)
+- DX polish: status, diff, sync, clean (Phase 38)
+
+**Plan:** `docs/plans/multi-runtime-skill-portability.md`
+
+## Shipped: v2.2.2 Documentation Audit & Multi-CLI Guides (2026-03-17)
+
+All documentation audited against source code, per-CLI usage guides created for Claude Code/Gemini/OpenCode, feature docs for external logging/lint/test. 11/11 requirements satisfied, 4 phases, 8 plans.
 
 ### Out of Scope
 
@@ -130,6 +167,9 @@ See REQUIREMENTS.md for next milestone requirements when defined.
 | LazyLock pre-compiled validators | <0.1ms validation overhead at runtime | ✓ Good |
 | ubuntu-22.04 for Tauri builds | webkit2gtk-4.1 requirement, ubuntu-latest may break | ✓ Good |
 | E2E gate before Tauri builds | Fast feedback (2-3min) prevents expensive failed builds | ✓ Good |
+| Hardcoded Rust transforms, not YAML-configurable | 4 well-known runtimes + Custom variant covers long tail | — Pending |
+| Clean-install writer (rm + recreate) | Prevents orphan files across versions, proven in GSD | — Pending |
+| `rulez skills` subcommand family, not extending `rulez install` | Hook registration and skill distribution are orthogonal | — Pending |
 
 ## Quality Gates
 
@@ -148,6 +188,6 @@ See REQUIREMENTS.md for next milestone requirements when defined.
 
 ---
 
-*Last updated: 2026-03-13 after v2.2.1 milestone*
+*Last updated: 2026-03-16 after v2.3.0 milestone start*
 *Reorganized as monorepo on 2026-02-06*
 *Renamed from CCH to RuleZ*

.planning/REQUIREMENTS.md

@@ -1,193 +1,95 @@
-# Requirements: RuleZ UI v1.6
+# Requirements: RuleZ Multi-Runtime Skill Portability
 
-**Defined:** 2026-02-11
-**Core Value:** LLMs do not enforce policy. LLMs are subject to policy.
+**Defined:** 2026-03-16
+**Core Value:** Author skills once in `.claude/`, convert at install time, run everywhere.
 
-## v1.6 Requirements
+## v2.3.0 Requirements
 
-Requirements for the RuleZ UI milestone. Each maps to roadmap phases.
+### Profiles — Runtime profiles and discovery
 
-### Rename Fix
+- [x] **PROFILE-01**: Runtime profiles define per-platform conventions (skills dir, commands dir, command separator, tool name style, path prefix)
+- [x] **PROFILE-02**: Skill discovery scans `.claude/skills/` and `.claude/commands/` building a manifest of skills and commands
+- [x] **PROFILE-03**: Extra skill sources outside standard location (mastering-hooks at repo root) discovered automatically
+- [x] **PROFILE-04**: Custom runtime support via `--dir` flag for generic skill targets
 
-- [ ] **RENAME-01**: User sees `rulez` (not `cch`) in all UI labels, commands, and config paths
-- [ ] **RENAME-02**: Tauri backend invokes `rulez` binary (not `cch`) for debug and validation commands
-- [ ] **RENAME-03**: Log file path defaults to `~/.claude/logs/rulez.log` (not `cch.log`)
+### Transform — Content transformation engine
 
-### YAML Editor
+- [x] **XFORM-01**: Tool names converted from Claude PascalCase to runtime conventions (lowercase for OpenCode, snake_case for Gemini)
+- [x] **XFORM-02**: Path references rewritten (`~/.claude/` -> `~/.config/opencode/`, `~/.gemini/`, `~/.codex/`)
+- [x] **XFORM-03**: Command filenames flattened from dot-separated to hyphen-separated with cross-reference rewriting
+- [x] **XFORM-04**: YAML frontmatter converted (allowed-tools -> tools format, color hex, strip unsupported fields)
+- [x] **XFORM-05**: MCP tools excluded for Gemini (auto-discovered), preserved for OpenCode/Codex
 
-- [ ] **EDIT-01**: User gets schema-driven autocomplete suggestions when typing YAML rule fields
-- [ ] **EDIT-02**: User sees inline error markers (red squiggles) for invalid YAML syntax and schema violations
-- [ ] **EDIT-03**: User can click errors in an error panel to jump to the corresponding line
-- [ ] **EDIT-04**: User can format/indent YAML on save or via keyboard shortcut
-- [ ] **EDIT-05**: Editor properly disposes Monaco models and workers when switching files (no memory leaks)
-- [ ] **EDIT-06**: User sees a live preview panel showing parsed rules with matched event types and actions
+### CLI — CLI integration and file writer
 
-### Log Viewer
+- [x] **CLI-01**: `rulez skills install --runtime <rt>` installs transformed skills to target runtime directory
+- [x] **CLI-02**: `rulez skills install --dry-run` previews what would be installed without writing
+- [x] **CLI-03**: `rulez skills clean --runtime <rt>` removes generated skill files for a runtime
+- [x] **CLI-04**: Clean-install writer removes existing target directory before writing fresh
 
-- [ ] **LOG-01**: User can view audit log entries from `~/.claude/logs/rulez.log` in a scrollable list
-- [ ] **LOG-02**: User can search/filter log entries by text content
-- [ ] **LOG-03**: User can filter log entries by severity level (error, warn, info, debug)
-- [ ] **LOG-04**: User can filter log entries by time range (date picker)
-- [ ] **LOG-05**: Log viewer handles large files (100K+ entries) with virtual scrolling at 60fps
-- [ ] **LOG-06**: User can export filtered log results to a file (JSON/CSV)
-- [ ] **LOG-07**: User can copy individual log entries to clipboard
+### Config — Config file generation
 
-### Config Management
+- [x] **CONFIG-01**: After installing to `.gemini/skills/`, auto-update `GEMINI.md` skill registry section using `<!-- RULEZ_SKILLS_START -->` / `<!-- RULEZ_SKILLS_END -->` markers
+- [x] **CONFIG-02**: Auto-generate `AGENTS.md` for Codex with skill registry section
+- [x] **CONFIG-03**: Preserve non-skill sections of config files during update
+- [x] **CONFIG-04**: Mastering-hooks platform references rewritten with context-aware handling (lives at repo root, not in `.claude/skills/`)
 
-- [ ] **CFG-01**: User can switch between global (`~/.claude/hooks.yaml`) and project (`.claude/hooks.yaml`) configs
-- [ ] **CFG-02**: User sees visual indicator of which config scope is active (global vs project)
-- [ ] **CFG-03**: User can import a config file from disk (file picker, YAML validated before applying)
-- [ ] **CFG-04**: User can export current config to a file
-- [ ] **CFG-05**: User sees config precedence (project overrides global) clearly indicated in the UI
-- [ ] **CFG-06**: Config changes auto-reload when the file is modified externally (file watching with debounce)
+### DX — Developer experience polish
 
-### Debug Simulator
+- [x] **DX-01**: `rulez skills status` shows human-readable relative timestamps (e.g., "2 hours ago") and mtime freshness comparison
+- [x] **DX-02**: `rulez skills diff --runtime <rt>` shows colored diff of what would change if skills were re-installed
+- [x] **DX-03**: `rulez skills sync` installs to all detected runtimes in one command with per-runtime progress
+- [x] **DX-04**: Colorized terminal output with progress indicators for install/sync operations
 
-- [ ] **DBG-01**: User can run debug simulation using the real `rulez debug` binary (not mock data)
-- [ ] **DBG-02**: User sees step-by-step rule evaluation trace showing which rules matched and why
-- [ ] **DBG-03**: User can save debug test cases (event + expected result) for reuse
-- [ ] **DBG-04**: User can load and replay saved test cases
-- [ ] **DBG-05**: Binary path is auto-detected from PATH with fallback to manual configuration
+## Future Requirements
 
-### Settings
+### Extended Portability
+- **PORT-01**: Copilot VSCode extension skill generation (different model from file-based skills)
+- **PORT-02**: Watch mode that auto-reinstalls when `.claude/skills/` changes
+- **PORT-03**: YAML-configurable transformation rules for custom runtimes
 
-- [ ] **SET-01**: User can toggle theme (light/dark/system) from a settings panel
-- [ ] **SET-02**: User can configure editor font size and tab size
-- [ ] **SET-03**: User can configure the path to the `rulez` binary
-- [ ] **SET-04**: Settings persist across app restarts (Tauri store or equivalent)
-
-### Onboarding
-
-- [ ] **OB-01**: First-time users see a setup wizard on initial app launch
-- [ ] **OB-02**: Wizard detects whether `rulez` binary is installed and accessible
-- [ ] **OB-03**: Wizard generates a sample `hooks.yaml` config with documented example rules
-- [ ] **OB-04**: Wizard guides user through a test simulation to verify setup works
-- [ ] **OB-05**: User can re-run onboarding from settings panel
-
-### E2E Testing
-
-- [ ] **E2E-01**: All new UI features have Playwright E2E tests in web mode
-- [ ] **E2E-02**: E2E tests cover editor, log viewer, config management, simulator, settings, and onboarding
-- [ ] **E2E-03**: E2E test suite passes in CI (GitHub Actions) on ubuntu, macOS, and Windows
-
-## Future Requirements (v1.7+)
-
-### OpenCode Plugin Integration
-
-- [ ] **OPENCODE-01**: Emit RuleZ hook events from OpenCode plugin lifecycle (file.edited, tool.execute.before/after, session.updated)
-- [ ] **OPENCODE-02**: Map OpenCode event context (project, directory, worktree, client SDK, shell $) to RuleZ event payload
-- [ ] **OPENCODE-03**: Inject RuleZ responses (block/allow, inject context) back into OpenCode plugin flow
-- [ ] **OPENCODE-04**: Register custom OpenCode tools that invoke RuleZ binary for policy checks
-- [ ] **OPENCODE-05**: Support OpenCode plugin config (`~/.config/opencode/plugins/rulez-plugin/`)
-- [ ] **OPENCODE-06**: Log all OpenCode-RuleZ interactions to audit trail with plugin metadata
-
-### Gemini CLI Hook Integration
-
-- [ ] **GEMINI-01**: Detect Gemini CLI hook events (write_file, replace, afterAgent) and translate to RuleZ format
-- [ ] **GEMINI-02**: Map Gemini CLI hook matchers to RuleZ event types (PreToolUse, PostToolUse equivalents)
-- [ ] **GEMINI-03**: Return structured JSON responses matching Gemini CLI hook response schema (deny/allow with reason)
-- [ ] **GEMINI-04**: Support Gemini CLI extensions that bundle RuleZ hooks (`~/.gemini/hooks/`)
-- [ ] **GEMINI-05**: Enable secret scanning and iterative loop patterns via RuleZ rules (e.g., "Ralph loop")
-- [ ] **GEMINI-06**: Document Gemini CLI→RuleZ translation layer with installation guide
-
-### GitHub Copilot Extension Integration
-
-- [ ] **COPILOT-01**: Create VS Code Copilot Chat participant that queries RuleZ for policy decisions
-- [ ] **COPILOT-02**: Integrate RuleZ with Copilot Language Model API for inline chat policy checks
-- [ ] **COPILOT-03**: Support slash commands in Copilot Chat that trigger RuleZ debug/explain/validate
-- [ ] **COPILOT-04**: Inject RuleZ context into Copilot prompts via Chat API message attachments
-- [ ] **COPILOT-05**: Block/warn on Copilot code suggestions that violate RuleZ policies (pre-acceptance hook)
-- [ ] **COPILOT-06**: Log all Copilot-RuleZ interactions to audit trail with extension metadata
-- [ ] **COPILOT-07**: Publish VS Code extension to marketplace with RuleZ binary bundled or auto-downloaded
-
-## Future Requirements (v2+)
-
-### Deferred Differentiators
-
-- **DIFF-01**: Rule-to-log correlation (click log entry to see which rule fired) — requires log format changes
-- **DIFF-02**: Replay saved events from logs (time-travel debugging)
-- **DIFF-03**: Multi-config comparison with Monaco diff editor
-- **DIFF-04**: Real-time log streaming (live tail in UI)
-
-### Out of Scope
+## Out of Scope
 
 | Feature | Reason |
 |---------|--------|
-| Visual rule builder (drag-drop) | Conflicts with YAML-first design philosophy |
-| AI-powered rule suggestions | Requires LLM integration, out of scope for desktop tool |
-| Cloud sync for configs | Adds auth/server complexity, use git instead |
-| Mobile app | Web-first approach, desktop is primary |
-| Script sandboxing UI | Cross-platform complexity, defer to v2+ |
+| Copilot skill distribution | VSCode extension model is fundamentally different from file-based skills |
+| YAML-configurable transforms | 4 well-known runtimes have stable conventions; Custom variant handles long tail |
+| Global skill registry/marketplace | Not needed for single-project portability |
+| Bidirectional sync (other -> Claude) | One canonical source (Claude Code), convert outward only |
 
 ## Traceability
 
 | Requirement | Phase | Status |
 |-------------|-------|--------|
-| RENAME-01 | Phase 11 | Pending |
-| RENAME-02 | Phase 11 | Pending |
-| RENAME-03 | Phase 11 | Pending |
-| SET-01 | Phase 11 | Pending |
-| SET-02 | Phase 11 | Pending |
-| SET-03 | Phase 11 | Pending |
-| SET-04 | Phase 11 | Pending |
-| DBG-05 | Phase 11 | Pending |
-| EDIT-01 | Phase 12 | Pending |
-| EDIT-02 | Phase 12 | Pending |
-| EDIT-03 | Phase 12 | Pending |
-| EDIT-04 | Phase 12 | Pending |
-| EDIT-05 | Phase 12 | Pending |
-| EDIT-06 | Phase 12 | Pending |
-| LOG-01 | Phase 13 | Pending |
-| LOG-02 | Phase 13 | Pending |
-| LOG-03 | Phase 13 | Pending |
-| LOG-04 | Phase 13 | Pending |
-| LOG-05 | Phase 13 | Pending |
-| LOG-06 | Phase 13 | Pending |
-| LOG-07 | Phase 13 | Pending |
-| CFG-01 | Phase 14 | Pending |
-| CFG-02 | Phase 14 | Pending |
-| CFG-03 | Phase 14 | Pending |
-| CFG-04 | Phase 14 | Pending |
-| CFG-05 | Phase 14 | Pending |
-| CFG-06 | Phase 14 | Pending |
-| DBG-01 | Phase 15 | Pending |
-| DBG-02 | Phase 15 | Pending |
-| DBG-03 | Phase 15 | Pending |
-| DBG-04 | Phase 15 | Pending |
-| OB-01 | Phase 16 | Pending |
-| OB-02 | Phase 16 | Pending |
-| OB-03 | Phase 16 | Pending |
-| OB-04 | Phase 16 | Pending |
-| OB-05 | Phase 16 | Pending |
-| E2E-01 | Phase 17 | Pending |
-| E2E-02 | Phase 17 | Pending |
-| E2E-03 | Phase 17 | Pending |
-| OPENCODE-01 | Phase 18 | Pending |
-| OPENCODE-02 | Phase 18 | Pending |
-| OPENCODE-03 | Phase 18 | Pending |
-| OPENCODE-04 | Phase 18 | Pending |
-| OPENCODE-05 | Phase 18 | Pending |
-| OPENCODE-06 | Phase 18 | Pending |
-| GEMINI-01 | Phase 19 | Pending |
-| GEMINI-02 | Phase 19 | Pending |
-| GEMINI-03 | Phase 19 | Pending |
-| GEMINI-04 | Phase 19 | Pending |
-| GEMINI-05 | Phase 19 | Pending |
-| GEMINI-06 | Phase 19 | Pending |
-| COPILOT-01 | Phase 20 | Pending |
-| COPILOT-02 | Phase 20 | Pending |
-| COPILOT-03 | Phase 20 | Pending |
-| COPILOT-04 | Phase 20 | Pending |
-| COPILOT-05 | Phase 20 | Pending |
-| COPILOT-06 | Phase 20 | Pending |
-| COPILOT-07 | Phase 20 | Pending |
+| PROFILE-01 | Phase 34 | Complete |
+| PROFILE-02 | Phase 34 | Complete |
+| PROFILE-03 | Phase 34 | Complete |
+| PROFILE-04 | Phase 34 | Complete |
+| XFORM-01 | Phase 35 | Complete |
+| XFORM-02 | Phase 35 | Complete |
+| XFORM-03 | Phase 35 | Complete |
+| XFORM-04 | Phase 35 | Complete |
+| XFORM-05 | Phase 35 | Complete |
+| CLI-01 | Phase 36 | Complete |
+| CLI-02 | Phase 36 | Complete |
+| CLI-03 | Phase 36 | Complete |
+| CLI-04 | Phase 36 | Complete |
+| CONFIG-01 | Phase 37 | Complete |
+| CONFIG-02 | Phase 37 | Complete |
+| CONFIG-03 | Phase 37 | Complete |
+| CONFIG-04 | Phase 37 | Complete |
+| DX-01 | Phase 38 | Complete |
+| DX-02 | Phase 38 | Complete |
+| DX-03 | Phase 38 | Complete |
+| DX-04 | Phase 38 | Complete |
 
 **Coverage:**
-- v1.6 requirements: 38 total
-- v1.7 requirements: 19 total (6 OpenCode + 6 Gemini + 7 Copilot)
-- Mapped to phases: 57/57 (100%)
-- Unmapped: 0
+- v2.3.0 requirements: 21 total
+- Mapped to phases: 21
+- Unmapped: 0 ✓
+- Complete: 21 (Phases 34-38)
+- Pending: 0 ✓
 
 ---
-*Requirements defined: 2026-02-11*
-*Last updated: 2026-02-11 after v1.7 phases added*
+*Requirements defined: 2026-03-16*
+*Last updated: 2026-03-17 after roadmap creation*