docs: add formal LaTeX ADR and update test harness

- Introduce `docs/adr-tex-2/`: A comprehensive Architecture Decision Record implemented in LaTeX.
- Document core architectural principles: "Zero-Database," "Empty Tree" commits, and the `@git-stunts/*` module decomposition.
- Add TikZ figures for System Context, Component Decomposition, Runtime Sequences, and Deployment Topologies.
- Add `Makefile` for PDF compilation and update `.gitignore` for LaTeX build artifacts.
- Update `test/setup.bats`: Adjust assertions to match specific prompt text ("Would you like me to clone it now") and enable debug logging for the setup script test.

Author: flyingrobots

.gitignore

@@ -7,3 +7,9 @@ cms-chunks-*/
 cms-upload-*/
 git-cms-test-*/
 .obsidian/
+
+# LaTeX artifacts
+*.aux 
+*.log
+*.out
+*.toc

docs/adr-tex-2/Makefile

@@ -0,0 +1,8 @@
+all: main.pdf
+
+main.pdf: main.tex $(wildcard sections/*.tex) $(wildcard figures/*.tex)
+	pdflatex -interaction=nonstopmode main.tex
+	pdflatex -interaction=nonstopmode main.tex
+
+clean:
+	rm -f *.aux *.log *.out *.toc *.pdf

docs/adr-tex-2/figures/context.tex

@@ -0,0 +1,12 @@
+\begin{tikzpicture}[node distance=2cm, auto]
+    \node [block] (Author) {Author\\(Human)};
+    \node [block, below=1cm of Author] (GitCMS) {\textbf{git-cms}\\(Node.js App)};
+    \node [block, right=2cm of GitCMS] (Stargate) {git-stargate\\(Git Gateway)};
+    \node [block, below=1cm of GitCMS] (LocalRepo) {.git/objects/\\(Local Repository)};
+    \node [block, right=2cm of Stargate] (PublicMirror) {Public Mirror\\(GitHub/GitLab)};
+
+    \draw [line] (Author) -- node [align=center, scale=0.8] {CLI/HTTP API} (GitCMS);
+    \draw [line] (GitCMS) -- node [scale=0.8] {git push} (Stargate);
+    \draw [line] (GitCMS) -- node [scale=0.8] {read/write} (LocalRepo);
+    \draw [line] (Stargate) -- node [scale=0.8] {mirror} (PublicMirror);
+\end{tikzpicture}

docs/adr-tex-2/figures/decomposition.tex

@@ -0,0 +1,21 @@
+\begin{tikzpicture}[node distance=1.5cm, auto]
+    \node [blockshaded] (CMS) {\textbf{CmsService}\\\texttt{src/lib}};
+    \node [block, above left=1cm and 0.5cm of CMS] (CLI) {CLI\\\texttt{bin/git-cms.js}};
+    \node [block, above right=1cm and 0.5cm of CMS] (HTTP) {HTTP Server\\\texttt{src/server}};
+    \node [draw, dashed, thick, inner sep=10pt, fit=(CLI) (HTTP) (CMS)] (AppLayer) {};
+    \node [anchor=south] at (AppLayer.north) {\small\textbf{Application Layer}};
+
+    \node [block, below=1.5cm of CMS] (Graph) {Graph\\empty-graph};
+    \node [block, left=0.5cm of Graph] (Codec) {Codec\\trailer-codec};
+    \node [block, right=0.5cm of Graph] (CAS) {CAS\\cas};
+    \node [block, below=1cm of Graph] (Plumbing) {Plumbing\\git-protocol};
+    \node [block, right=0.5cm of CAS] (Vault) {Vault\\secrets};
+    \node [draw, dashed, thick, inner sep=10pt, fit=(Plumbing) (Codec) (Graph) (CAS) (Vault)] (LegoLayer) {};
+    \node [anchor=north] at (LegoLayer.south) {\small\textbf{Lego Blocks (@git-stunts)}};
+
+    \draw [line] (CLI) -- (CMS); \draw [line] (HTTP) -- (CMS);
+    \draw [line] (CMS) -- (Codec); \draw [line] (CMS) -- (Graph);
+    \draw [line] (CMS) -- (CAS); \draw [line] (CMS) -- (Vault);
+    \draw [line] (CMS) -- (Plumbing); \draw [line] (Graph) -- (Plumbing);
+    \draw [line] (CAS) -- (Plumbing);
+\end{tikzpicture}

docs/adr-tex-2/figures/draft-sequence.tex

@@ -0,0 +1,18 @@
+\begin{tikzpicture}[node distance=3cm, auto]
+    \node (Author) {Author};
+    \node [right=of Author] (CLI) {CLI};
+    \node [right=of CLI] (CMS) {Service};
+    \node [right=of CMS] (PL) {Plumbing};
+
+    \foreach \n in {Author, CLI, CMS, PL} {
+        \draw [dashed] (\n) -- ++(0,-6.5);
+    }
+
+    \draw [->] ($(Author)+(0,-1)$) -- node [scale=0.7] {draft hello-world} ($(CLI)+(0,-1)$);
+    \draw [->] ($(CLI)+(0,-1.5)$) -- node [scale=0.7] {saveSnapshot()} ($(CMS)+(0,-1.5)$);
+    \draw [->] ($(CMS)+(0,-2.2)$) -- node [scale=0.7] {revParse(ref)} ($(PL)+(0,-2.2)$);
+    \draw [<-] ($(CMS)+(0,-3)$) -- node [scale=0.7] {null} ($(PL)+(0,-3)$);
+    \draw [->] ($(CMS)+(0,-4)$) -- node [scale=0.7] {createNode()} ($(CMS)+(0.8,-4.2)$);
+    \draw [->] ($(CMS)+(0,-5)$) -- node [scale=0.7] {updateRef()} ($(PL)+(0,-5)$);
+    \draw [<-] ($(CLI)+(0,-6)$) -- node [scale=0.7] {OK} ($(CMS)+(0,-6)$);
+\end{tikzpicture}

docs/adr-tex-2/figures/responsibilities.tex

@@ -0,0 +1,17 @@
+\begin{tikzpicture}[node distance=1cm, auto, font=\small]
+    \node [blockshaded, text width=2.5cm, minimum height=8cm] (CMS) {\textbf{CmsService}};
+    \node [block, text width=4.5cm, right=3cm of CMS.north, anchor=north] (PL) {\textbf{@git-stunts/plumbing}\\execute, revParse};
+    \node [block, text width=4.5cm, below=0.5cm of PL] (TC) {\textbf{@git-stunts/trailer-codec}\\encode, decode};
+    \node [block, text width=4.5cm, below=0.5cm of TC] (EG) {\textbf{@git-stunts/empty-graph}\\createNode, readNode};
+    \node [block, text width=4.5cm, below=0.5cm of EG] (CAS) {\textbf{@git-stunts/cas}\\storeFile, retrieveFile};
+    \node [block, text width=4.5cm, below=0.5cm of CAS] (V) {\textbf{@git-stunts/vault}\\resolveSecret};
+
+    \draw [line] (CMS.east |- PL.west) -- (PL.west);
+    \draw [line] (CMS.east |- TC.west) -- (TC.west);
+    \draw [line] (CMS.east |- EG.west) -- (EG.west);
+    \draw [line] (CMS.east |- CAS.west) -- (CAS.west);
+    \draw [line] (CMS.east |- V.west) -- (V.west);
+
+    \draw [dashed-line] (EG.east) -- ++(0.5,0) |- (PL.east);
+    \draw [dashed-line] (CAS.east) -- ++(0.5,0) |- (PL.east);
+\end{tikzpicture}

docs/adr-tex-2/main.pdf

@@ -0,0 +1,113 @@
+\documentclass[11pt,a4paper]{article}
+
+% --- Packages ---
+\usepackage[utf8]{inputenc}
+\usepackage[T1]{fontenc}
+\usepackage{lmodern} 
+\usepackage[margin=1in, headheight=14pt]{geometry} 
+\usepackage{titlesec}
+\usepackage{titletoc}
+\usepackage{fancyhdr}
+\usepackage{graphicx} 
+\usepackage{booktabs} 
+\usepackage{longtable}
+\usepackage{array}
+\usepackage{enumitem} 
+\usepackage{float}
+\usepackage{listings}
+\usepackage{xcolor}
+\usepackage{tikz}
+\usetikzlibrary{shapes, arrows.meta, positioning, fit, backgrounds, calc, shadows, trees}
+\usepackage{amssymb} 
+\usepackage{xurl} 
+\usepackage[hidelinks]{hyperref}
+
+% --- Typography & Layout ---
+\hypersetup{
+    colorlinks=false,
+    pdftitle={Architecture Decision Record: Git CMS},
+    pdfauthor={James Ross}
+}
+
+\usepackage{parskip}
+\setlength{\parindent}{0pt}
+\setlength{\parskip}{0.8em}
+
+\pagestyle{fancy}
+\fancyhf{}
+\fancyhead[L]{\nouppercase{\leftmark}}
+\fancyhead[R]{Git CMS ADR}
+\fancyfoot[C]{\thepage}
+
+\titleformat{\section}{\Large\bfseries\sffamily}{\thesection}{1em}{}
+\titleformat{\subsection}{\large\bfseries\sffamily}{\thesubsection}{1em}{}
+\titleformat{\subsubsection}{\bfseries\sffamily}{\thesubsubsection}{1em}{}
+
+\lstset{
+    basicstyle=\ttfamily\small,
+    breaklines=true,
+    frame=single, 
+    numbers=left,
+    numberstyle=\tiny\color{gray},
+    captionpos=b,
+    keepspaces=true,
+    showstringspaces=false,
+    keywordstyle=\bfseries, 
+    commentstyle=\itshape,  
+    stringstyle=,           
+}
+
+% --- Textbook B&W TikZ Styles ---
+\tikzset{
+    base/.style={draw=black, thick, font=\sffamily\small, align=center, inner sep=8pt},
+    block/.style={base, rectangle, rounded corners=2pt, fill=white},
+    blockshaded/.style={base, rectangle, rounded corners=2pt, fill=gray!10},
+    line/.style={draw=black, thick, -Latex},
+    dashed-line/.style={draw=black, thick, dashed, -Latex}
+}
+
+\begin{document}
+
+\input{meta}
+
+\begin{titlepage}
+    \centering
+    \vspace*{3cm}
+    {\fontsize{30}{36}\selectfont \textbf{Architecture Decision Record}\\[0.5em]}
+    {\fontsize{20}{24}\selectfont \textit{Git CMS}\\[1.5cm]}
+    
+    \rule{\textwidth}{1pt}\\[0.5cm]
+    {\Large Database-Free Content Management via Git Plumbing}\\[3cm]
+    
+    \textbf{Author:} James Ross \\
+    \textbf{Version:} 1.0.0 \\
+    \textbf{Date:} 2026-01-11
+    
+    \vfill
+    \textit{Prepared for Engineering Review}
+    \vspace{2cm}
+\end{titlepage}
+
+\tableofcontents
+\newpage
+
+\input{sections/01-introduction}
+\input{sections/02-constraints}
+\input{sections/03-context}
+\input{sections/04-solution}
+\input{sections/05-building-blocks}
+\input{sections/06-runtime}
+\input{sections/07-deployment}
+\input{sections/08-crosscutting}
+\input{sections/09-decisions}
+\input{sections/10-quality}
+\input{sections/11-risks}
+\input{sections/12-glossary}
+
+\appendix
+\input{sections/A-commands}
+\input{sections/B-structure}
+\input{sections/C-related}
+\input{sections/D-references}
+
+\end{document}

docs/adr-tex-2/main.tex

@@ -0,0 +1,5 @@
+% meta.tex
+\title{\textbf{Architecture Decision Record: Git CMS}\\ \large Database-Free Content Management via Git Plumbing}
+\author{James Ross}
+\date{Version 1.0.0 -- Last Updated: 2026-01-11}
+

docs/adr-tex-2/meta.tex

@@ -0,0 +1,64 @@
+\section{Introduction \& Goals}
+
+\subsection{Project Overview}
+
+\textbf{git-cms} is a serverless, database-free Content Management System that treats Git's object store as a distributed, cryptographically verifiable document database. Instead of storing content in traditional databases (SQL or NoSQL), it leverages Git's Merkle DAG to create an append-only ledger for articles, metadata, and encrypted assets.
+
+The fundamental innovation: \texttt{git push} becomes the API endpoint.
+
+\subsection{Fundamental Requirements}
+
+\subsubsection{FR-1: Zero-Database Architecture}
+The system MUST NOT depend on external database systems (SQL, NoSQL, or key-value stores). All persistent state resides within Git's native object store (\texttt{.git/objects}).
+
+\textbf{Rationale:} Eliminates operational complexity, deployment dependencies, and schema migration challenges inherent to traditional database-backed CMSs.
+
+\subsubsection{FR-2: Cryptographic Verifiability}
+Every content mutation MUST be recorded as a Git commit with cryptographic integrity guarantees via SHA-1 hashing (with optional GPG signing for non-repudiation).
+
+\textbf{Rationale:} Provides immutable audit trails and tamper detection without additional infrastructure.
+
+\subsubsection{FR-3: Fast-Forward Only Publishing}
+The publish operation MUST enforce strict linear history (fast-forward only) to prevent rewriting published content.
+
+\textbf{Rationale:} Guarantees provenance and prevents content manipulation after publication.
+
+\subsubsection{FR-4: Client-Side Encryption}
+All uploaded assets MUST be encrypted client-side (AES-256-GCM) before touching the repository.
+
+\textbf{Rationale:} Achieves row-level security without database-level access controls. The Git gateway receives only opaque encrypted blobs.
+
+\subsubsection{FR-5: Infinite Point-in-Time Recovery}
+Users MUST be able to access any historical version of any article without data loss.
+
+\textbf{Rationale:} Git's DAG structure provides this naturally; the CMS simply exposes it as a first-class feature.
+
+\subsection{Quality Goals}
+
+\begin{table}[H]
+\centering
+\small
+\begin{tabular}{llp{5cm}p{4cm}}
+\toprule
+\textbf{Prio} & \textbf{Attribute} & \textbf{Description} & \textbf{Measurement} \\
+\midrule
+1 & Security & Cryptographic integrity, signed commits & GPG verification, AES-256 strength \\
+2 & Simplicity & Minimal dependencies, composable architecture & Lines of code, dependency count \\
+3 & Auditability & Complete provenance of all content changes & Git log completeness \\
+4 & Performance & Sub-second reads for blog workloads & Response time for \texttt{readArticle()} \\
+5 & Portability & Multi-runtime support (Node, Bun, Deno) & Test suite pass rate \\
+\bottomrule
+\end{tabular}
+\caption{Quality goals and their measurements.}
+\end{table}
+
+\subsection{Non-Goals}
+
+This system is \textbf{intentionally NOT designed for}:
+
+\begin{itemize}[noitemsep]
+    \item \textbf{High-velocity writes:} Content publishing happens in minutes/hours, not milliseconds.
+    \item \textbf{Complex queries:} No SQL-like JOINs or aggregations. Queries are limited to ref enumeration and commit message parsing.
+    \item \textbf{Large-scale collaboration:} Designed for single-author or small-team blogs.
+    \item \textbf{Real-time updates:} Publishing is atomic but not instantaneous.
+\end{itemize}