rosett-ai 1.3.3

data/doc/reference/error-catalog.md

@@ -0,0 +1,107 @@
+# Error Catalog
+
+This document lists all error classes in rosett-ai, their exit codes, and usage
+contexts. Every error follows the **what/why/fix** message pattern.
+
+## Exit Codes
+
+| Code | Name | Meaning |
+|------|------|---------|
+| 0 | SUCCESS | Command completed without error |
+| 1 | GENERAL | Runtime or unexpected error |
+| 2 | VALIDATION | Input, schema, or rule validation failed |
+| 3 | CONFIG | Configuration missing or invalid |
+| 4 | PERMISSION | Insufficient permissions |
+| 5 | DEPENDENCY | Missing external dependency |
+
+## Error Classes
+
+### Exit Code 1 (GENERAL)
+
+| Class | Context |
+|-------|---------|
+| `RosettAi::Error` | Base error class; catch-all for unspecified failures |
+| `RosettAi::AdoptError` | Adopt command failures (local analysis or remote API) |
+| `RosettAi::BackupError` | Backup creation or restoration failures |
+| `RosettAi::BuildError` | Package build failures (.deb generation) |
+| `RosettAi::DocumentationError` | Documentation generation failures |
+| `RosettAi::ReleaseError` | Release preparation or tagging failures |
+| `RosettAi::ContentError` | Content pack install, update, or list failures |
+| `RosettAi::ProvenanceError` | AI provenance tracking failures |
+| `RosettAi::AuthorshipError` | AI authorship attribution failures |
+
+### Exit Code 2 (VALIDATION)
+
+| Class | Context |
+|-------|---------|
+| `RosettAi::ValidationError` | Schema validation, input validation, YAML errors |
+| `RosettAi::BehaviourError` | Behaviour file loading or validation |
+| `RosettAi::DesignError` | Design document validation |
+| `RosettAi::CompositionError` | Behaviour composition conflicts or cycles |
+| `RosettAi::CompileError` | Compilation failures (rule rendering, lockfile) |
+| `RosettAi::ToolingError` | Tooling validation failures (CI YAML, versions) |
+
+### Exit Code 3 (CONFIG)
+
+| Class | Context |
+|-------|---------|
+| `RosettAi::ConfigurationError` | Missing or malformed configuration |
+| `RosettAi::AiConfigError` | AI tool configuration failures |
+| `RosettAi::PolicyError` | Policy management failures |
+| `RosettAi::InitError` | Init command failures (directory creation, config) |
+| `RosettAi::LicenseError` | License activation or validation failures |
+
+## Message Format
+
+Error messages follow the **what/why/fix** pattern:
+
+```text
+Error [CODE]: <what went wrong>
+  Why: <root cause>
+  Fix: <actionable suggestion>
+  Type: <error class>
+```
+
+The `Why:` and `Fix:` sections are optional. When `RAI_LOG_LEVEL=DEBUG`,
+a backtrace (limited to 10 frames) is appended.
+
+### Example
+
+```text
+Error [3]: Missing API key
+  Why: ANTHROPIC_API_KEY not set in environment
+  Fix: export ANTHROPIC_API_KEY=sk-...
+  Type: RosettAi::ConfigurationError
+```
+
+## TTY-Aware Output
+
+When stderr is a TTY (interactive terminal):
+
+- Error line: **red bold**
+- Why line: **yellow**
+- Fix line: **green**
+- Type line: **dim**
+
+When stderr is piped (non-interactive), plain text is used without colour.
+
+## Raising Errors
+
+Use the what/why/fix delimiters in the message string:
+
+```ruby
+raise RosettAi::ConfigurationError,
+      'Missing API key. Why: ANTHROPIC_API_KEY not set. Fix: export ANTHROPIC_API_KEY=sk-...'
+```
+
+The `ErrorHandler` parses ` Why: ` and ` Fix: ` as delimiters (note the
+leading space before each keyword).
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `lib/rosett_ai.rb` | Error class definitions |
+| `lib/rosett_ai/exit_codes.rb` | Exit code constants and mapping |
+| `lib/rosett_ai/error_handler.rb` | Centralized error handler |
+| `conf/design/error_handling.yml` | Design document |

data/doc/reference/src/StyleInd.ist

@@ -0,0 +1,4 @@
+delim_0 "\\dotfill\ "
+delim_1 "\\dotfill\ "
+headings_flag 1
+heading_prefix "\\vspace*{0.5cm}\\nopagebreak\n\\tikz\\node at (0pt,0pt) [rounded corners=5pt,draw=ocre,fill=ocre!10,line width=1pt,inner sep=5pt]{\\parbox{\\linewidth-2\\fboxsep-2\\fboxrule-2pt}{\\centering\\large\\sffamily\\bfseries\\textcolor{black}{" heading_suffix "}}};\\vspace*{0.2cm}\\nopagebreak\n"

data/doc/reference/src/bibliography.bib

@@ -0,0 +1,79 @@
+@online{semver,
+  author = {Preston-Werner, Tom},
+  title = {Semantic Versioning 2.0.0},
+  year = {2013},
+  url = {https://semver.org/},
+  urldate = {2026-02-22}
+}
+
+@online{keepachangelog,
+  author = {Langlois, Olivier},
+  title = {Keep a Changelog 1.1.0},
+  year = {2017},
+  url = {https://keepachangelog.com/},
+  urldate = {2026-02-22}
+}
+
+@online{jsonschema,
+  author = {{JSON Schema Contributors}},
+  title = {JSON Schema Specification 2020-12},
+  year = {2022},
+  url = {https://json-schema.org/specification},
+  urldate = {2026-02-22}
+}
+
+@online{claudecode,
+  author = {{Anthropic}},
+  title = {Claude Code Documentation},
+  year = {2026},
+  url = {https://docs.anthropic.com/en/docs/claude-code},
+  urldate = {2026-02-22}
+}
+
+@online{en301549,
+  author = {{ETSI}},
+  title = {EN 301 549 -- Accessibility Requirements for ICT Products and Services},
+  year = {2021},
+  url = {https://www.etsi.org/deliver/etsi_en/301500_301599/301549/},
+  urldate = {2026-02-22}
+}
+
+@online{gpl3,
+  author = {{Free Software Foundation}},
+  title = {GNU General Public License, Version 3},
+  year = {2007},
+  url = {https://www.gnu.org/licenses/gpl-3.0.html},
+  urldate = {2026-02-22}
+}
+
+@online{jwt,
+  author = {Jones, M. and Bradley, J. and Sakimura, N.},
+  title = {JSON Web Token (JWT) -- RFC 7519},
+  year = {2015},
+  url = {https://tools.ietf.org/html/rfc7519},
+  urldate = {2026-02-22}
+}
+
+@online{ed25519,
+  author = {Bernstein, D.J. and Duif, N. and Lange, T. and Schwabe, P. and Yang, B.},
+  title = {High-speed high-security signatures -- Ed25519},
+  year = {2012},
+  url = {https://ed25519.cr.yp.to/},
+  urldate = {2026-02-22}
+}
+
+@online{pulp,
+  author = {{Pulp Project}},
+  title = {Pulp -- Software Repository Management},
+  year = {2026},
+  url = {https://pulpproject.org/},
+  urldate = {2026-02-22}
+}
+
+@online{gitcliff,
+  author = {Sever, Orhun Parmaks{\i}z},
+  title = {git-cliff -- Changelog Generator},
+  year = {2026},
+  url = {https://git-cliff.org/},
+  urldate = {2026-02-22}
+}