rosett-ai 1.3.3

data/doc/reference/src/main.tex

@@ -0,0 +1,1288 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%  NeatNerds Code Companion -- Technical Reference
+%  Comprehensive reference for all design documents, architectural decisions,
+%  schemas, and configuration settings.
+%
+%  Owner: Hugo Antonio Sepulveda Manriquez (hugo@neatnerds.be)
+%
+%  Based on the template: Clustering the Interstellar Medium
+%  https://www.overleaf.com/articles/clustering-the-interstellar-medium/mtthgyyfrdkn
+%  Licensed under the LaTeX Project Public License 1.3c
+%
+%  Chapter heading images should have a 2:1 width:height ratio.
+%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+%------------------------------------------------------------------------------
+%   PACKAGES AND OTHER DOCUMENT CONFIGURATIONS
+%------------------------------------------------------------------------------
+
+\documentclass[11pt,fleqn]{book}
+
+\usepackage[top=3cm,bottom=3cm,left=3cm,right=3cm,headsep=10pt,a4paper]{geometry}
+
+\usepackage{xcolor}
+\definecolor{ocre}{RGB}{52,177,201}
+
+% Font Settings
+\usepackage{avant}
+\usepackage{mathptmx}
+
+\usepackage{microtype}
+\usepackage[utf8]{inputenc}
+\usepackage[T1]{fontenc}
+
+% Bibliography
+\usepackage[style=alphabetic,sorting=nyt,sortcites=true,autopunct=true,
+autolang=hyphen,hyperref=true,abbreviate=false,backref=true,backend=biber]{
+biblatex}
+\addbibresource{bibliography.bib}
+\defbibheading{bibempty}{}
+
+\input{structure}
+
+\begin{document}
+
+%------------------------------------------------------------------------------
+%   TITLE PAGE
+%------------------------------------------------------------------------------
+
+\begingroup
+\thispagestyle{empty}
+\AddToShipoutPicture*{\put(0,0){\includegraphics[scale=1.25]{cover}}}
+\centering
+\vspace*{5cm}
+\par\normalfont\fontsize{35}{35}\sffamily\selectfont
+\textbf{\textcolor{white}{NeatNerds Code Companion}}\\[0.5cm]
+{\LARGE \textcolor{white}{Technical Reference \& Design Specification}}\par
+\vspace*{1.5cm}
+{\Large \textcolor{white}{Version 1.0.0}}\par
+\vspace*{0.5cm}
+{\large \textcolor{white}{Hugo Antonio Sepulveda Manriquez}}\par
+\endgroup
+
+%------------------------------------------------------------------------------
+%   COPYRIGHT PAGE
+%------------------------------------------------------------------------------
+
+\newpage
+~\vfill
+\thispagestyle{empty}
+
+\noindent \textsc{NeatNerds -- Antwerp, Belgium}\\
+
+\noindent \textsc{https://gitlab.neatnerds.be/neatnerds/nncc}\\
+
+\noindent Licensed under the GNU General Public License v3.0 only
+(GPL-3.0-only).\\
+This is free software: you are free to change and redistribute it under
+the terms of the GPL-3.0-only license.\cite{gpl3}\\
+
+\noindent \textit{First edition, February 2026}
+
+%------------------------------------------------------------------------------
+%   TABLE OF CONTENTS
+%------------------------------------------------------------------------------
+
+\chapterimage{head1.jpg}
+
+\pagestyle{empty}
+
+\tableofcontents
+
+\pagestyle{fancy}
+
+\cleardoublepage
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%   CHAPTER 1: PROJECT OVERVIEW
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\chapterimage{head2.jpg}
+\chapter{Project Overview}\label{ch:overview}
+
+\section{Introduction}\index{Introduction}
+
+The \textbf{NeatNerds Code Companion} (\texttt{nncc}) is a Ruby-based
+configuration management tool for AI-assisted development workflows. It provides a
+structured, schema-validated approach to managing AI assistant configurations,
+compiling them into target-specific output formats (Claude Code, Cursor, AGENTS.md,
+and more), and enforcing security and quality standards throughout the
+development lifecycle.
+
+\begin{constraintbox}
+\textbf{Core Principle:} Author once, compile to many. A single set of YAML
+source files is compiled into configurations for Claude, Mistral, GPT-NeoX,
+or any generic AI assistant target.
+\end{constraintbox}
+
+\section{Project Identity}\index{Project Identity}
+
+\begin{longtable}{ll}
+\toprule
+\textbf{Field} & \textbf{Value} \\
+\midrule
+Project Name & nncc \\
+Full Name & NeatNerds Code Companion \\
+Author & Hugo Antonio Sepulveda Manriquez \\
+Contact & hugo@neatnerds.be \\
+License & GPL-3.0-only \\
+Ruby Version & 3.3.10 (via rbenv) \\
+Repository & gitlab.neatnerds.be/neatnerds/nncc \\
+Version & 0.1.0 \\
+\bottomrule
+\end{longtable}
+
+\section{Architecture at a Glance}\index{Architecture}
+
+The system follows a layered architecture with clear extension points:
+
+\begin{lstlisting}[language={},caption={Layer architecture}]
+CLI Layer        lib/nncc/thor/tasks/*.rb      Thor subcommands
+Library Layer    lib/nncc/**/*.rb              Domain logic
+Config Layer     conf/**/*.yml                 YAML configurations
+Schema Layer     conf/schemas/*.json           JSON Schema validation
+Compiler Layer   lib/nncc/compiler/backends/   AI target backends
+UI Layer         lib/nncc/ui/                  Pluggable display adapters
+i18n Layer       locales/*.yml                 Translation files
+\end{lstlisting}
+
+\section{Implementation Priority}\index{Priority}
+
+Design documents are implemented in strict priority order, with security
+and quality gates established before any feature code:
+
+\begin{longtable}{clp{9cm}}
+\toprule
+\textbf{Priority} & \textbf{Tier} & \textbf{Documents} \\
+\midrule
+P1 & Foundation & security, testing, styles, ci\_pipeline \\
+P2 & Structure & architecture, compiler, claude\_code\_configuration \\
+P3 & Interface & ui\_framework, accessibility, i18n \\
+P4 & Business & licensing\_system, content\_packs \\
+P5 & Operations & release\_management, documentation, distribution \\
+\bottomrule
+\end{longtable}
+
+\begin{criterionbox}
+\textbf{Rule:} Guardrails before features. Validation before implementation.
+No feature code merges until P1 gates exist.
+\end{criterionbox}
+
+\section{Key Decisions}\index{Key Decisions}
+
+\begin{itemize}
+\item \textbf{GPL-3.0-only} -- open-core model: software is free, premium
+      content is paid
+\item \textbf{TUI-first} with pluggable GUI: \texttt{nncc},
+      \texttt{nncc-gtk4}, \texttt{nncc-qt6}, \texttt{nncc-kde}
+\item \textbf{Multi-target AI} -- author once, compile to
+      Claude/Mistral/GPT-NeoX/generic
+\item \textbf{Mutant} as independent test quality validator (three-party model)
+\item \textbf{Ed25519-signed JWT}\cite{ed25519,jwt} license keys,
+      offline-verifiable
+\item \textbf{EN 301 549}\cite{en301549} (EU) accessibility compliance
+\item \textbf{UTF-8 everywhere}, Linux/Debian only initially
+\end{itemize}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%   CHAPTER 2: P1 FOUNDATION
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\chapterimage{head3.jpg}
+\chapter{P1 -- Foundation}\label{ch:p1}
+
+Priority 1 establishes the security, testing, style, and CI foundations
+that all subsequent work depends on.
+
+\section{Security}\index{Security}
+
+\subsection{Intent}
+
+Define and enforce security boundaries for every operation \texttt{nncc}
+performs. Security is not a feature -- it is a constraint that applies to
+every line of code, every file operation, and every external interaction.
+
+\subsection{Core Constraints}
+
+\begin{constraintbox}
+\begin{enumerate}
+\item \textbf{YAML.safe\_load only} -- never \texttt{YAML.load}
+      (arbitrary code execution risk)
+\item \textbf{Array-form system()} -- never string interpolation
+      in shell commands (injection risk)
+\item \textbf{File writes to whitelisted directories only} -- prevent
+      path traversal
+\item \textbf{Secrets at 0600 permissions} -- never logged, never in
+      version control
+\item \textbf{All external input validated before use} -- schema
+      validation for YAML, JSON Schema for configs
+\end{enumerate}
+\end{constraintbox}
+
+\subsection{Secret Management}
+
+Secrets are referenced using a DSL convention:
+
+\begin{lstlisting}[language=yaml,caption={Secret reference DSL}]
+api:
+  key: "${secret:env:ANTHROPIC_API_KEY}"
+  auth_token: "${secret:file:~/.config/nncc/token}"
+\end{lstlisting}
+
+The \texttt{SecretsResolver} class resolves these references at runtime
+from environment variables, files, or system keyrings. The reference
+string itself is never a secret -- it is a pointer.
+
+\subsection{Input Validation}
+
+Every YAML file loaded by \texttt{nncc} is validated against its JSON
+Schema before any data is used. The validation chain:
+
+\begin{enumerate}
+\item \texttt{YAML.safe\_load} -- parse safely
+\item \texttt{JSONSchemer.schema} -- validate against schema
+\item Domain-specific checks -- e.g., permission patterns, version
+      constraints
+\end{enumerate}
+
+\subsection{File Permission Model}
+
+\begin{longtable}{lll}
+\toprule
+\textbf{File Type} & \textbf{Mode} & \textbf{Rationale} \\
+\midrule
+License keys & 0600 & Contains subscription identity \\
+Configuration & 0644 & Readable, owner-writable \\
+Executables & 0755 & Standard Unix convention \\
+Directories & 0755 & Standard traversal \\
+Secret dirs & 0700 & Owner-only access \\
+\bottomrule
+\end{longtable}
+
+\begin{antipatternbox}
+\textbf{Anti-patterns:}
+\begin{itemize}
+\item Using \texttt{YAML.load} with untrusted input
+\item Building shell commands with string interpolation
+\item Writing files outside the whitelisted directories
+\item Logging secret values, even at debug level
+\item Storing secrets in YAML configuration files
+\end{itemize}
+\end{antipatternbox}
+
+\section{Testing}\index{Testing}
+
+\subsection{Intent}
+
+Ensure every component has meaningful, fast tests that catch regressions
+early. The testing strategy uses a three-party model: RSpec for
+specifications, SimpleCov for coverage measurement, and Mutant as an
+independent test quality validator.
+
+\subsection{Testing Pyramid}
+
+\begin{longtable}{lp{5cm}p{5cm}}
+\toprule
+\textbf{Level} & \textbf{Scope} & \textbf{Tools} \\
+\midrule
+Unit & Individual classes/methods & RSpec + factory\_bot \\
+Integration & Module interactions & RSpec + tmpdir isolation \\
+Mutation & Test quality validation & Mutant (mutant-rspec) \\
+Security & Vulnerability scanning & bundler-audit, ruby-audit \\
+Style & Code consistency & RuboCop, Reek \\
+\bottomrule
+\end{longtable}
+
+\subsection{Constraints}
+
+\begin{constraintbox}
+\begin{itemize}
+\item RSpec suite must pass with 0 failures before any commit
+\item Coverage target: 90\%+ line coverage (SimpleCov)
+\item Mutation testing validates test effectiveness -- tests that
+      do not detect mutations are insufficient
+\item All specs run in isolation -- no shared mutable state, no
+      filesystem leaks
+\item Test fixtures use \texttt{factory\_bot} -- never hand-crafted
+      hashes
+\end{itemize}
+\end{constraintbox}
+
+\section{Styles}\index{Styles}
+
+\subsection{Intent}
+
+Enforce consistent code style across all Ruby source files. Style rules
+are not aesthetic preferences -- they are communication standards that
+reduce cognitive load during code review.
+
+\subsection{Tool Configuration}
+
+\begin{longtable}{lll}
+\toprule
+\textbf{Tool} & \textbf{Config} & \textbf{Standard} \\
+\midrule
+RuboCop & .rubocop.yml & 0 offenses required \\
+Reek & .reek.yml & 0 warnings (or justified exclusions) \\
+Flay & (Rakefile) & Duplication monitoring \\
+\bottomrule
+\end{longtable}
+
+\subsection{Key Style Rules}
+
+\begin{itemize}
+\item \textbf{Frozen string literals} -- every Ruby file starts with
+      \texttt{\# frozen\_string\_literal: true}
+\item \textbf{SPDX headers} -- every Ruby file includes
+      \texttt{\# SPDX-License-Identifier: GPL-3.0-only}
+\item \textbf{UTF-8 encoding} -- no Latin-1, no BOM markers
+\item \textbf{2-space indentation} -- Ruby community standard
+\item \textbf{No trailing whitespace} -- enforced by pre-commit hooks
+\end{itemize}
+
+\section{CI Pipeline}\index{CI Pipeline}
+
+\subsection{Intent}
+
+Automate all verification steps so that no broken code reaches the main
+branch. The CI pipeline mirrors the pre-commit hook chain but runs in an
+isolated, reproducible environment.
+
+\subsection{Pipeline Stages}
+
+\begin{longtable}{llp{7cm}}
+\toprule
+\textbf{Stage} & \textbf{Job} & \textbf{Description} \\
+\midrule
+validate & yaml\_lint & YAML syntax validation \\
+code\_quality & rubocop & Style enforcement (0 offenses) \\
+code\_quality & reek & Code smell detection \\
+code\_quality & flay & Duplication detection \\
+security\_scan & bundler\_audit & Gem CVE scanning \\
+security\_scan & ruby\_audit & Ruby CVE scanning \\
+security\_scan & gitleaks & Secret detection \\
+test & rspec & Full test suite \\
+build & package & Debian package build \\
+\bottomrule
+\end{longtable}
+
+\begin{criterionbox}
+\textbf{CI Rule:} All stages must pass before merge. There are no
+``allowed failures'' in the pipeline.
+\end{criterionbox}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%   CHAPTER 3: P2 STRUCTURE
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\chapterimage{head4.jpg}
+\chapter{P2 -- Structure}\label{ch:p2}
+
+Priority 2 builds the core structural components: the modular architecture,
+the multi-target compiler, and the Claude Code configuration management
+system.
+
+\section{Architecture}\index{Architecture}
+
+\subsection{Intent}
+
+Define the modular structure that allows \texttt{nncc} to grow without
+becoming a monolith. Each module has a single responsibility, clear
+interfaces, and minimal coupling.
+
+\subsection{Module Map}
+
+\begin{longtable}{lp{9cm}}
+\toprule
+\textbf{Module} & \textbf{Responsibility} \\
+\midrule
+\texttt{Nncc::Thor} & CLI interface (Thor subcommands) \\
+\texttt{Nncc::Compiler} & Multi-target compilation pipeline \\
+\texttt{Nncc::Config} & Claude Code configuration management \\
+\texttt{Nncc::Security} & Secret resolution, input validation \\
+\texttt{Nncc::Ui} & Pluggable UI adapters (TUI/GUI) \\
+\texttt{Nncc::Licensing} & Ed25519 JWT license validation \\
+\texttt{Nncc::I18n} & Locale resolution and string externalization \\
+\texttt{Nncc::ContentPack} & Premium content pack management \\
+\bottomrule
+\end{longtable}
+
+\subsection{Path Resolution}
+
+All filesystem paths are resolved through \texttt{Nncc::PathResolver},
+ensuring consistent path computation regardless of the current working
+directory. Key paths:
+
+\begin{lstlisting}[language=ruby,caption={Path resolution}]
+Nncc.paths.root          # Project root
+Nncc.paths.conf_dir      # conf/
+Nncc.paths.rules_dir     # ~/.claude/rules/
+Nncc.paths.license_file  # ~/.config/nncc/license.key
+Nncc.paths.premium_content_dir  # ~/.local/share/nncc/content/
+\end{lstlisting}
+
+\begin{decisionbox}
+\textbf{ADR-001: PathResolver centralisation.} All path computation goes
+through a single resolver class to prevent path drift between modules.
+Each method returns a \texttt{Pathname} object for safe path manipulation.
+\end{decisionbox}
+
+\section{Compiler}\index{Compiler}
+
+\subsection{Intent}
+
+Transform YAML source configurations into target-specific output formats.
+The compiler uses a strategy pattern where each AI target has a
+\texttt{Backend} class and a \texttt{TargetProfile} YAML configuration.
+
+\subsection{Compilation Pipeline}
+
+The \texttt{CompilationPipeline} class orchestrates the full flow:
+
+\begin{enumerate}
+\item \textbf{Discovery} -- scan \texttt{conf/} for categories that
+      have matching schemas
+\item \textbf{Loading} -- parse YAML with \texttt{YAML.safe\_load}
+\item \textbf{Validation} -- verify against JSON Schema
+\item \textbf{Rendering} -- delegate to the backend for format-specific
+      output
+\item \textbf{Checksumming} -- SHA-256 digest for change detection
+\item \textbf{Orphan cleanup} -- remove managed files that no longer
+      have sources
+\end{enumerate}
+
+\subsection{Backend Architecture}
+
+\begin{lstlisting}[language=ruby,caption={Backend registration}]
+BACKENDS = {
+  'claude'  => 'Nncc::Compiler::Backends::ClaudeBackend',
+  'generic' => 'Nncc::Compiler::Backends::GenericBackend'
+}.freeze
+\end{lstlisting}
+
+Each backend implements:
+\begin{itemize}
+\item \texttt{render(category, data)} -- produce output string
+\item \texttt{generated\_marker} -- identify managed files
+\item \texttt{file\_extension} -- output format (\texttt{.md} for markdown)
+\end{itemize}
+
+\subsection{Target Profiles}
+
+\begin{lstlisting}[language=yaml,caption={Claude target profile}]
+name: claude
+description: Claude Code (Anthropic) target
+backend: claude
+engine_version: ">=1.0.0"
+output_format: markdown
+output_dir: null
+max_context_window: 200000
+rendering:
+  include_source_metadata: true
+  include_priority_annotations: true
+  include_generated_marker: true
+\end{lstlisting}
+
+\begin{decisionbox}
+\textbf{ADR-005: Multi-engine architecture.} Adding a new AI target
+requires only a YAML profile and a Ruby backend class. No changes to
+the compilation pipeline, CLI, or test infrastructure.
+\end{decisionbox}
+
+\section{Claude Code Configuration}\index{Claude Code Configuration}
+
+\subsection{Intent}
+
+Manage Claude Code settings across four scopes: user, project, local,
+and managed. Each scope compiles to a specific JSON file that Claude Code
+reads at runtime.
+
+\subsection{Scope Hierarchy}
+
+\begin{longtable}{llp{6cm}}
+\toprule
+\textbf{Scope} & \textbf{Output Path} & \textbf{Purpose} \\
+\midrule
+managed & /etc/claude-code/managed-settings.json & Enterprise policies \\
+user & \textasciitilde/.claude/settings.json & User defaults \\
+project & .claude/settings.json & Project-specific \\
+local & .claude/settings.local.json & Local overrides (gitignored) \\
+\bottomrule
+\end{longtable}
+
+\subsection{Key Mapping}
+
+YAML source files use \texttt{snake\_case} keys which are transformed
+to \texttt{camelCase} for the JSON output that Claude Code expects.
+The \texttt{KeyMap} class handles this transformation:
+
+\begin{lstlisting}[language=ruby,caption={Key mapping example}]
+# YAML source
+auto_allow_bash: true
+max_output_tokens: 32000
+
+# JSON output
+"autoAllowBash": true,
+"maxOutputTokens": 32000
+\end{lstlisting}
+
+\subsection{Permission Model}
+
+Permissions are structured as allow/deny/ask lists with glob patterns:
+
+\begin{lstlisting}[language=yaml,caption={Permission configuration}]
+permissions:
+  default_mode: acceptEdits
+  allow:
+    - "Bash(bundle *)"
+    - "Bash(bin/nncc *)"
+    - "Bash(rbenv *)"
+  deny:
+    - "Read(./.env)"
+    - "Read(~/.ssh/**/*)"
+    - "Read(~/.gnupg/**/*)"
+  ask:
+    - "Bash(git push *)"
+\end{lstlisting}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%   CHAPTER 4: P3 INTERFACE
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\chapterimage{head5.jpg}
+\chapter{P3 -- Interface}\label{ch:p3}
+
+Priority 3 implements the user-facing interface layer: pluggable UI
+adapters, accessibility compliance, and internationalization.
+
+\section{UI Framework}\index{UI Framework}
+
+\subsection{Intent}
+
+Provide a pluggable display layer that decouples domain logic from
+presentation. The default is a terminal UI (TUI); GUI adapters are
+optional extensions distributed as separate Debian packages.
+
+\subsection{Adapter Registry}
+
+The \texttt{Nncc::Ui::Registry} class manages adapter discovery
+and resolution:
+
+\begin{lstlisting}[language=ruby,caption={UI adapter registration}]
+Registry.register(:tui, Tui)
+Registry.register(:accessible_tui, AccessibleTui)
+Registry.register(:gtk4, Gtk4)
+Registry.register(:qt6, Qt6)
+Registry.register(:kde, Kde)
+\end{lstlisting}
+
+\subsection{Package Variants}
+
+\begin{longtable}{llp{6cm}}
+\toprule
+\textbf{Package} & \textbf{Adapter} & \textbf{System Dependencies} \\
+\midrule
+nncc & tui & ruby, libncurses \\
+nncc-gtk4 & gtk4 & nncc, libgtk-4-dev, ruby-gnome \\
+nncc-qt6 & qt6 & nncc (placeholder -- bindings pending) \\
+nncc-kde & kde & nncc-qt6 (placeholder -- bindings pending) \\
+\bottomrule
+\end{longtable}
+
+\begin{decisionbox}
+\textbf{ADR-002: UI adapter registry.} Adding a new GUI adapter
+requires only a Ruby class implementing the \texttt{Base} interface
+and a packaging variant YAML. The CLI \texttt{--ui} flag selects
+the adapter at runtime.
+\end{decisionbox}
+
+\subsection{Base Interface}
+
+Every UI adapter must implement five methods:
+
+\begin{longtable}{lp{6.5cm}}
+\toprule
+\textbf{Method} & \textbf{Purpose} \\
+\midrule
+\texttt{render(content)} & Display text to the user \\
+\texttt{display\_table(h, rows)} & Display tabular data \\
+\texttt{prompt\_user(q, choices:)} & Interactive input \\
+\texttt{show\_spinner(msg, \&blk)} & Progress indication \\
+\texttt{announce(message)} & Accessibility announcement \\
+\bottomrule
+\end{longtable}
+
+\section{Accessibility}\index{Accessibility}
+
+\subsection{Intent}
+
+Ensure \texttt{nncc} is usable by people with disabilities, in compliance
+with EN 301 549 (EU accessibility standard)\cite{en301549}. This is not
+optional -- it is a legal requirement for publicly-funded ICT in the EU.
+
+\subsection{Implementation}
+
+The \texttt{AccessibleTui} adapter provides:
+
+\begin{itemize}
+\item \textbf{Linear output} -- no box-drawing characters, no
+      decorative ANSI escapes
+\item \textbf{NO\_COLOR support} -- respects the \texttt{NO\_COLOR}
+      environment variable
+\item \textbf{Screen reader compatibility} -- tested with Orca and BRLTTY
+\item \textbf{Auto-detection} -- switches to accessible mode when
+      \texttt{ORCA\_RUNNING} or \texttt{BRLTTY\_TTY} is set
+\item \textbf{Announcement priorities} -- \texttt{:polite} and
+      \texttt{:assertive} levels for screen reader output
+\item \textbf{RTL support} -- detects RTL locales (Arabic, Hebrew)
+      and adjusts text direction
+\end{itemize}
+
+\begin{constraintbox}
+\textbf{Accessibility constraint:} Every UI adapter must pass the
+shared example \texttt{it\_behaves\_like 'a UI implementation'}
+which verifies all five interface methods are implemented.
+\end{constraintbox}
+
+\section{Internationalization}\index{Internationalization}
+
+\subsection{Intent}
+
+Externalize all user-facing strings so that \texttt{nncc} can be used
+in any language. The i18n system uses ruby-i18n with YAML source files.
+
+\subsection{Locale Resolution}
+
+The \texttt{LocaleResolver} determines the active locale through a
+priority chain:
+
+\begin{enumerate}
+\item \texttt{--locale} CLI flag (highest priority)
+\item \texttt{NNCC\_LOCALE} environment variable
+\item \texttt{LANG} environment variable
+\item English fallback (lowest priority)
+\end{enumerate}
+
+\subsection{Translation Structure}
+
+\begin{lstlisting}[language=yaml,caption={Locale file structure}]
+en:
+  nncc:
+    meta:
+      direction: ltr
+      language_name: "English"
+    cli:
+      version: "nncc Version %{version}"
+      compile:
+        compiling: "Compiling %{category}..."
+        success: "Compiled %{count} files"
+\end{lstlisting}
+
+\subsection{UTF-8 Enforcement}
+
+A \texttt{TextSanitizer} module enforces UTF-8 throughout:
+
+\begin{itemize}
+\item \texttt{normalize\_nfc(text)} -- Unicode NFC normalization
+\item \texttt{strip\_ansi(text)} -- remove ANSI escape sequences
+\item \texttt{valid\_utf8?(text)} -- encoding validation
+\end{itemize}
+
+\subsection{Locale Compilation}
+
+The \texttt{LocaleCompiler} transforms YAML locale files into
+distribution formats:
+
+\begin{longtable}{llp{5cm}}
+\toprule
+\textbf{Format} & \textbf{Extension} & \textbf{Use Case} \\
+\midrule
+Gettext & .pot/.po & GNU toolchain integration \\
+Qt Linguist & .ts & Qt6 GUI adapter \\
+\bottomrule
+\end{longtable}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%   CHAPTER 5: P4 BUSINESS
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\chapterimage{head6.jpg}
+\chapter{P4 -- Business}\label{ch:p4}
+
+Priority 4 implements the business model: an open-core licensing system
+where the software is free (GPL-3.0) and premium content packs are paid.
+
+\section{Licensing System}\index{Licensing}
+
+\subsection{Intent}
+
+Enable a sustainable open-source business model. The licensing system
+controls access to premium content packs -- it NEVER restricts software
+functionality. This distinction is critical for GPL-3.0 compliance.
+
+\begin{criterionbox}
+\textbf{GPL-3.0 compliance rule:} License tiers gate content pack
+\emph{downloads}, not software features. A community user has full
+access to all \texttt{nncc} functionality -- they simply do not have
+access to premium behaviour and design packs.
+\end{criterionbox}
+
+\subsection{License Key Format}
+
+License keys are Ed25519-signed JWTs\cite{jwt,ed25519} with an
+\texttt{NNCC-} prefix:
+
+\begin{lstlisting}[language={},caption={License key structure}]
+NNCC-eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9...
+\end{lstlisting}
+
+JWT claims include:
+\begin{longtable}{llp{5cm}}
+\toprule
+\textbf{Claim} & \textbf{Type} & \textbf{Description} \\
+\midrule
+tier & string & community, supporter, subscriber, enterprise \\
+exp & integer & Expiry timestamp (Unix epoch) \\
+perpetual & boolean & Perpetual license flag \\
+sub & string & Subscriber identifier \\
+\bottomrule
+\end{longtable}
+
+\subsection{Tier Hierarchy}
+
+\begin{longtable}{clp{6cm}}
+\toprule
+\textbf{Level} & \textbf{Tier} & \textbf{Access} \\
+\midrule
+0 & Community & Free software, no premium content \\
+1 & Supporter & Basic premium packs \\
+2 & Subscriber & All premium packs + updates \\
+3 & Enterprise & All packs + priority support \\
+\bottomrule
+\end{longtable}
+
+\subsection{Grace Periods}
+
+\begin{longtable}{lll}
+\toprule
+\textbf{Period} & \textbf{Duration} & \textbf{Behaviour} \\
+\midrule
+Active & Until expiry & Full access \\
+Grace & 14 days post-expiry & Access with warning \\
+Offline & 30 days & Verify without network \\
+Expired & After grace & Content frozen at last version \\
+\bottomrule
+\end{longtable}
+
+\subsection{Storage Security}
+
+The \texttt{LicenseStore} class persists the license key at
+\texttt{\textasciitilde/.config/nncc/license.key} with:
+
+\begin{itemize}
+\item File mode \texttt{0600} (owner read/write only)
+\item Directory mode \texttt{0700} (owner access only)
+\item UID verification (must match current process)
+\end{itemize}
+
+\begin{antipatternbox}
+\textbf{Anti-patterns:}
+\begin{itemize}
+\item Restricting software features based on license tier (GPL violation)
+\item Storing license keys in YAML config files (wrong permissions)
+\item Logging license key contents
+\item Phone-home license validation (must work offline)
+\end{itemize}
+\end{antipatternbox}
+
+\section{Content Packs}\index{Content Packs}
+
+\subsection{Intent}
+
+Distribute premium behaviour and design packs to licensed users. Content
+packs are the revenue mechanism that sustains the open-source project.
+
+\subsection{Pack Structure}
+
+\begin{lstlisting}[language=yaml,caption={Content pack manifest}]
+name: enterprise_security
+version: 1.0.0
+tier_required: subscriber
+description: "Advanced security behaviours for enterprise"
+author: "NeatNerds"
+contents:
+  behaviours:
+    - advanced_audit.yml
+    - compliance_reporting.yml
+  designs:
+    - soc2_compliance.yml
+\end{lstlisting}
+
+\subsection{Installation Path}
+
+Premium content is installed to
+\texttt{\textasciitilde/.local/share/nncc/content/<pack\_name>/}
+and discovered automatically by the compilation pipeline.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%   CHAPTER 6: P5 OPERATIONS
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\chapterimage{head7.jpg}
+\chapter{P5 -- Operations}\label{ch:p5}
+
+Priority 5 covers operational concerns: release management, documentation
+generation, and package distribution.
+
+\section{Release Management}\index{Release Management}
+
+\subsection{Intent}
+
+Define a repeatable, automated process for releasing \texttt{nncc}
+versions. The release process eliminates manual version edits, manual
+CHANGELOG writing, and manual tag creation -- all sources of
+inconsistency and human error.
+
+\subsection{Release Workflow}
+
+\begin{enumerate}
+\item \texttt{bin/nncc release prepare LEVEL} --
+      bumps version, generates CHANGELOG, creates release commit
+\item Developer reviews the commit
+\item \texttt{bin/nncc release tag} -- creates annotated tag
+\item \texttt{git push origin branch --tags} -- triggers CI release
+\end{enumerate}
+
+\subsection{Constraints}
+
+\begin{constraintbox}
+\begin{itemize}
+\item Version follows Semantic Versioning 2.0.0\cite{semver}
+\item CHANGELOG follows Keep a Changelog 1.1.0\cite{keepachangelog}
+\item Full verification suite must pass before any release commit
+\item Version source of truth: \texttt{lib/nncc/version.rb}
+\item Tags are annotated (not lightweight) with pattern \texttt{vX.Y.Z}
+\item Release commits use \texttt{chore(release):} prefix
+\item Auto-push is forbidden -- push is always explicit
+\end{itemize}
+\end{constraintbox}
+
+\subsection{git-cliff Configuration}
+
+CHANGELOG generation uses git-cliff\cite{gitcliff} with conventional
+commit parsing:
+
+\begin{lstlisting}[language={},caption={Conventional commit mapping}]
+feat     -> Added
+fix      -> Fixed
+refactor -> Changed
+perf     -> Changed
+docs     -> Documentation
+chore    -> Other
+\end{lstlisting}
+
+\begin{antipatternbox}
+\textbf{Anti-patterns:}
+\begin{itemize}
+\item Auto-pushing to remote as part of the release process
+\item Editing CHANGELOG manually when automation exists
+\item Using lightweight git tags
+\item Coupling version bump and tag creation into one command
+\end{itemize}
+\end{antipatternbox}
+
+\section{Documentation}\index{Documentation}
+
+\subsection{Intent}
+
+Provide end users with complete documentation for installing, configuring,
+and using \texttt{nncc}. Three documentation tiers:
+
+\begin{longtable}{llp{6cm}}
+\toprule
+\textbf{Tier} & \textbf{Format} & \textbf{Audience} \\
+\midrule
+Man pages & ronn-ng (roff) & End users (\texttt{man nncc}) \\
+API docs & YARD (HTML) & Contributors \\
+Guides & Markdown & All (INSTALL.md, SETUP.md) \\
+\bottomrule
+\end{longtable}
+
+\subsection{Man Page Structure}
+
+\begin{lstlisting}[language={},caption={Man page sections}]
+NAME        - nncc -- NeatNerds Code Companion
+SYNOPSIS    - nncc [OPTIONS] COMMAND [ARGS]
+DESCRIPTION - Overview of what nncc does
+COMMANDS    - All CLI subcommands
+OPTIONS     - Global flags (--accessible, --locale, --ui)
+FILES       - Configuration file locations
+EXIT STATUS - Return codes and meanings
+ENVIRONMENT - Relevant environment variables
+SEE ALSO    - Related commands and resources
+\end{lstlisting}
+
+\subsection{Documentation Consistency}
+
+A CI job verifies documentation consistency:
+\begin{itemize}
+\item Ruby version in \texttt{doc/SETUP.md} matches \texttt{.ruby-version}
+\item Subcommands in man page match CLI \texttt{--help} output
+\item No stale version references in documentation files
+\end{itemize}
+
+\section{Distribution}\index{Distribution}
+
+\subsection{Intent}
+
+Deliver \texttt{nncc} Debian packages to end users through a managed
+APT repository. The distribution system uses Pulp\cite{pulp} as the
+repository management platform.
+
+\subsection{Packaging}
+
+The \texttt{bin/nncc build package} command creates Debian packages
+using fpm (Effing Package Management):
+
+\begin{longtable}{lp{8cm}}
+\toprule
+\textbf{Stage} & \textbf{Description} \\
+\midrule
+verify & Pre-flight checks (Ruby version, fpm, dpkg) \\
+clean & Reset staging directory \\
+stage\_ruby & Install gems to staging (--deployment) \\
+install\_bin & Copy executables \\
+install\_lib & Copy library files \\
+install\_conf & Copy configuration and schemas \\
+install\_locales & Copy translation files \\
+install\_man & Generate and install man pages \\
+fpm & Build .deb package \\
+verify\_deb & Validate package with dpkg-deb \\
+\bottomrule
+\end{longtable}
+
+\subsection{Repository Architecture}
+
+\begin{lstlisting}[language={},caption={Pulp repository layout}]
+Distribution:
+  nncc-stable    -> latest releases
+  nncc-testing   -> release candidates
+  nncc-nightly   -> CI builds (auto-pruned)
+
+Signing:
+  GPG Ed25519 or RSA-4096
+  SHA256+ digest only
+
+Phases:
+  Phase 1: pulp_deb (Debian/Ubuntu)
+  Phase 2: pulp_rpm (RHEL/Fedora) -- future
+  Phase 3: pulp_file (generic tarballs) -- future
+\end{lstlisting}
+
+\begin{decisionbox}
+\textbf{ADR: Pulp over aptly.} The distribution system uses
+Pulp instead of aptly because Pulp supports multi-format repositories
+(deb + rpm + file) through a plugin architecture, provides a REST API
+for CI integration, and runs in OCI containers for reproducibility.
+\end{decisionbox}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%   CHAPTER 7: LIFECYCLE MANAGEMENT
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\chapterimage{head8.jpg}
+\chapter{Lifecycle Management}\label{ch:lifecycle}
+
+\section{Intent}\index{Lifecycle Management}
+
+Define repeatable, auditable processes for upgrading software components
+(Ruby runtime, gems, system libraries, build tools) across the project.
+Upgrades are security-critical operations -- a missed CVE fix is a
+vulnerability, a botched upgrade is downtime.
+
+\section{Upgrade Methodology}\index{Upgrade Methodology}
+
+The lifecycle management methodology consists of six phases:
+
+\subsection{Phase 1: Discovery}
+
+\begin{itemize}
+\item Run security audit tools (\texttt{ruby-audit}, \texttt{bundler-audit})
+\item Record each CVE identifier, severity, and affected component
+\item Determine the minimum version that resolves all identified CVEs
+\end{itemize}
+
+\subsection{Phase 2: Research}
+
+\begin{itemize}
+\item Check official release pages for the target version
+\item Check version manager availability (\texttt{rbenv install --list})
+\item Read release notes for breaking changes or new deprecations
+\item Verify target version satisfies gemspec/dependency constraints
+\end{itemize}
+
+\subsection{Phase 3: Scope}
+
+\begin{itemize}
+\item Grep the entire codebase for all version references
+\item Categorize findings: config, docs, specs, build scripts
+\item Note any version-dependent logic in source code
+\end{itemize}
+
+\subsection{Phase 4: Execute}
+
+\begin{itemize}
+\item Install the new version
+\item Update version pins
+\item Reinstall dependencies
+\item Update all version references identified in scope phase
+\end{itemize}
+
+\subsection{Phase 5: Verify}
+
+\begin{longtable}{ll}
+\toprule
+\textbf{Check} & \textbf{Expected Result} \\
+\midrule
+ruby-audit & 0 vulnerabilities \\
+bundler-audit & 0 vulnerabilities \\
+RuboCop & 0 offenses \\
+Reek & 0 warnings \\
+RSpec & 0 failures \\
+Grep & No stale version references \\
+\bottomrule
+\end{longtable}
+
+\subsection{Phase 6: Commit}
+
+\begin{itemize}
+\item Stage only upgrade-related files
+\item Write commit message referencing CVEs or upgrade rationale
+\item Let pre-commit hooks run (never \texttt{--no-verify})
+\end{itemize}
+
+\section{Reference Execution}\index{Reference Execution}
+
+The methodology was derived from the Ruby 3.3.8 to 3.3.10 upgrade % rai:no-version-check
+(2026-02-19), triggered by \texttt{ruby-audit} flagging three CVEs:
+
+\begin{longtable}{lp{8cm}}
+\toprule
+\textbf{CVE} & \textbf{Description} \\
+\midrule
+CVE-2025-24294 & resolv library denial of service \\
+CVE-2025-58767 & REXML denial of service \\
+CVE-2025-61594 & URI credential leak \\
+\bottomrule
+\end{longtable}
+
+Verification results after upgrade:
+\begin{itemize}
+\item ruby-audit: 0 vulnerabilities
+\item RuboCop: 44 files, 0 offenses
+\item Reek: 0 warnings
+\item Flay: 199 total score (unchanged)
+\item RSpec: 277 examples, 0 failures
+\item Coverage: 92.92\%
+\end{itemize}
+
+\begin{antipatternbox}
+\textbf{Anti-patterns:}
+\begin{itemize}
+\item Upgrading without checking official release notes
+\item Partial version reference updates
+\item Running \texttt{bundle update} without targeting specific gems
+\item Skipping verification because ``it is just a patch version''
+\item Bypassing pre-commit hooks with \texttt{--no-verify}
+\item Mixing unrelated changes into an upgrade commit
+\end{itemize}
+\end{antipatternbox}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%   CHAPTER 8: SCHEMA REFERENCE
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\chapterimage{head1.jpg}
+\chapter{Schema Reference}\label{ch:schemas}
+
+All YAML configuration files are validated against JSON
+Schemas\cite{jsonschema} before use. This chapter documents each schema.
+
+\section{Design Document Schema}\index{Design Schema}
+
+Validates the structure of design documents in \texttt{conf/design/}.
+
+\begin{longtable}{llp{5cm}}
+\toprule
+\textbf{Field} & \textbf{Type} & \textbf{Description} \\
+\midrule
+name & string & Unique identifier (pattern: \texttt{[\^{}a-z0-9\_]}) \\
+domain & enum & core, ui, security, testing, styles, i18n, accessibility,
+         licensing, ci, compiler, release, documentation \\
+version & string & Semantic version (X.Y.Z) \\
+status & enum & draft, review, approved, deprecated \\
+priority & integer & 1--6 (P1=highest) \\
+author & string & Creator \\
+created\_at & date & ISO 8601 date \\
+modified\_at & date & Last modification date \\
+modified\_by & string & Last modifier \\
+depends\_on & array & List of dependency document names \\
+intent & string & Purpose and rationale \\
+constraints & array & Hard boundaries \\
+acceptance\_criteria & array & Testable done conditions \\
+examples & array & Usage scenarios \\
+anti\_patterns & array & What to avoid \\
+preferences & object & Implementation preferences \\
+\bottomrule
+\end{longtable}
+
+\section{Behaviour Schema}\index{Behaviour Schema}
+
+Validates behaviour configuration files in \texttt{conf/behaviour/}.
+
+\begin{longtable}{llp{5cm}}
+\toprule
+\textbf{Field} & \textbf{Type} & \textbf{Description} \\
+\midrule
+name & string & Unique identifier (1--100 chars) \\
+description & string & Human-readable explanation \\
+version & string & Semantic version \\
+author & string & Creator \\
+created\_at & date & Creation date \\
+modified\_at & date & Last modification \\
+modified\_by & string & Last modifier \\
+sensitive & boolean & Exclude from API analysis \\
+used\_in & array & Projects using this behaviour \\
+rules & array & Operational rules (min 1) \\
+\bottomrule
+\end{longtable}
+
+\subsection{Rule Schema}
+
+Each rule within a behaviour has:
+
+\begin{longtable}{llp{5cm}}
+\toprule
+\textbf{Field} & \textbf{Type} & \textbf{Description} \\
+\midrule
+id & string & Unique rule identifier \\
+description & string & What this rule instructs \\
+priority & integer & 1--100 (90--100 critical, 70--89 high,
+           50--69 medium, 30--49 low, 1--29 minimal) \\
+enabled & boolean & Whether rule is active \\
+\bottomrule
+\end{longtable}
+
+\section{Claude Code Config Schema}\index{CC Config Schema}
+
+Validates Claude Code configuration files in \texttt{conf/claude\_code/}.
+This is the most complex schema, covering all Claude Code settings.
+
+\subsection{Top-Level Sections}
+
+\begin{longtable}{lp{8cm}}
+\toprule
+\textbf{Section} & \textbf{Description} \\
+\midrule
+model & Default model, available models, effort level \\
+permissions & Allow/deny/ask lists with glob patterns \\
+sandbox & Network restrictions, command filtering \\
+context & Token limits, compaction threshold \\
+display & Language, progress bar, spinner configuration \\
+hooks & Pre/post tool-use event handlers \\
+mcp & Model Context Protocol server policies \\
+attribution & Commit and PR attribution strings \\
+api & API key helpers, provider configuration \\
+system & Auto-updates, cleanup, team mate mode \\
+env & Pass-through environment variables \\
+\bottomrule
+\end{longtable}
+
+\section{Target Profile Schema}\index{Target Schema}
+
+Validates compiler target profiles in \texttt{conf/targets/}.
+
+\begin{longtable}{llp{5cm}}
+\toprule
+\textbf{Field} & \textbf{Type} & \textbf{Description} \\
+\midrule
+name & string & Target identifier \\
+backend & enum & claude, generic \\
+output\_format & enum & markdown, json, yaml \\
+output\_dir & string/null & Override output directory \\
+max\_context\_window & integer/null & Max tokens \\
+rendering & object & Source metadata, priority annotations, marker \\
+\bottomrule
+\end{longtable}
+
+\section{Content Pack Manifest Schema}\index{Content Pack Schema}
+
+Validates premium content pack manifests.
+
+\begin{longtable}{llp{5cm}}
+\toprule
+\textbf{Field} & \textbf{Type} & \textbf{Description} \\
+\midrule
+name & string & Pack identifier (lowercase, underscores) \\
+version & string & Semantic version \\
+tier\_required & enum & supporter, subscriber, enterprise \\
+description & string & Human-readable description \\
+author & string & Pack author \\
+contents & object & behaviours and designs arrays \\
+\bottomrule
+\end{longtable}
+
+\section{Packaging Schema}\index{Packaging Schema}
+
+Validates Debian packaging variant configurations.
+
+\begin{longtable}{llp{5cm}}
+\toprule
+\textbf{Field} & \textbf{Type} & \textbf{Description} \\
+\midrule
+name & string & Debian package name (nncc*) \\
+variant & enum & core, gtk4, qt6, kde \\
+description & string & Package description \\
+ui\_adapter & enum & tui, gtk4, qt6, kde \\
+system\_dependencies & array & Debian package names \\
+package\_dependencies & array & nncc packages with versions \\
+\bottomrule
+\end{longtable}
+
+\section{Tooling Schema}\index{Tooling Schema}
+
+Validates the tool registry for external CLI tool management.
+
+\begin{longtable}{llp{5cm}}
+\toprule
+\textbf{Field} & \textbf{Type} & \textbf{Description} \\
+\midrule
+tools & object & Map of tool names to configs \\
+\quad description & string & Tool description \\
+\quad permission\_pattern & string & Claude Code pattern \\
+\quad category & enum & json, yaml, search, text, system, network \\
+\quad packages & object & Package manager to package name map \\
+\bottomrule
+\end{longtable}
+
+%------------------------------------------------------------------------------
+%   BIBLIOGRAPHY
+%------------------------------------------------------------------------------
+
+\chapter*{Bibliography}
+\addcontentsline{toc}{chapter}{\textcolor{ocre}{Bibliography}}
+
+\printbibliography[heading=bibempty]
+
+%------------------------------------------------------------------------------
+%   INDEX
+%------------------------------------------------------------------------------
+
+\cleardoublepage
+\phantomsection
+\setlength{\columnsep}{0.75cm}
+\addcontentsline{toc}{chapter}{\textcolor{ocre}{Index}}
+\printindex
+
+\end{document}