From dda2fc15b24688b0bb52d166f9b4a9f818a01c9d Mon Sep 17 00:00:00 2001
From: Your Name <you@example.com>
Date: Thu, 19 Mar 2026 21:27:36 +0000
Subject: [PATCH] Update docs and install script for Stack/GHC 9.10.3

Switch README and CLAUDE.md from cabal to stack commands, update GHC
version references, add pkg-config to install-deps.sh, and add Stack
as the recommended build method.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 CLAUDE.md       | 31 +++++++++++++++----------------
 README.md       | 41 +++++++++++++++++++++++++++++++----------
 install-deps.sh |  2 +-
 3 files changed, 47 insertions(+), 27 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 24e7062..2ac75ab 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -10,31 +10,36 @@ Docster is a Haskell CLI tool that converts Markdown files with embedded Mermaid
 
 ### Build
 ```bash
-cabal build
+stack build
 ```
 
 ### Run
 ```bash
 # Convert to PDF
-cabal run docster -- -pdf path/to/file.md
+stack exec docster -- -pdf path/to/file.md
 
-# Convert to HTML  
-cabal run docster -- -html path/to/file.md
+# Convert to HTML
+stack exec docster -- -html path/to/file.md
+```
+
+### Test
+```bash
+stack test
 ```
 
 ### Test a single file
 ```bash
-cabal run docster -- -pdf mermaid-to-svg/sample.md
+stack exec docster -- -pdf mermaid-to-svg/sample.md
 ```
 
 ### Clean build artifacts
 ```bash
-cabal clean
+stack clean
 ```
 
 ### Interactive development
 ```bash
-cabal repl
+stack repl
 ```
 
 ## Architecture
@@ -57,17 +62,11 @@ The tool uses Pandoc's AST transformation capabilities to:
 ## Dependencies
 
 External requirements:
-- GHC 9.12.2 and Cabal 3.16 (install via ghcup)
-- Pandoc library
+- Stack (install via ghcup) — manages GHC 9.10.3 automatically via lts-24.34
+- Pandoc library (Haskell dependency, pulled by Stack)
 - TeX Live (for PDF generation via XeLaTeX)
 - Mermaid CLI (`npm install -g @mermaid-js/mermaid-cli`)
-
-To install GHC and Cabal:
-```bash
-source ~/.ghcup/env && ghcup install ghc 9.12.2
-source ~/.ghcup/env && ghcup install cabal 3.16.0.0
-source ~/.ghcup/env && ghcup set ghc 9.12.2
-```
+- pkg-config, libgmp-dev, libffi-dev, zlib1g-dev (see `install-deps.sh`)
 
 ## Common Issues
 
diff --git a/README.md b/README.md
index c6f605d..31dc00e 100644
--- a/README.md
+++ b/README.md
@@ -13,12 +13,14 @@ Mermaid code blocks (```mermaid) will be rendered to SVG and embedded.
 
 ### Prerequisites
 
-First install the required system dependencies:
+Install the required system dependencies (Ubuntu/Debian):
 
 ```bash
 ./install-deps.sh
 ```
 
+This installs build-essential, libgmp-dev, libffi-dev, zlib1g-dev, pkg-config, and TeX Live packages for PDF generation.
+
 ### Install Haskell toolchain
 
 Install ghcup (Haskell toolchain installer):
@@ -28,13 +30,26 @@ curl --proto '=https' --tlsv1.2 -sSf https://get-ghcup.haskell.org | sh
 source ~/.ghcup/env
 ```
 
-Install specific GHC and Cabal versions:
+#### Option A: Build with Stack (recommended)
+
+Stack manages its own GHC installation automatically.
 
 ```bash
-ghcup install ghc 9.12.2
+ghcup install stack
+stack build
+stack install
+```
+
+This uses the resolver defined in `stack.yaml` (currently lts-24.34 / GHC 9.10.3).
+
+#### Option B: Build with Cabal
+
+```bash
+ghcup install ghc 9.10.3
 ghcup install cabal 3.16.0.0
-ghcup set ghc 9.12.2
+ghcup set ghc 9.10.3
 ghcup set cabal 3.16.0.0
+cabal install --installdir=$HOME/.local/bin
 ```
 
 ### Install Mermaid CLI
@@ -43,18 +58,24 @@ ghcup set cabal 3.16.0.0
 npm install -g @mermaid-js/mermaid-cli
 ```
 
-### Build and install docster
+### PATH setup
+
+Make sure the install location is in your PATH. Add to your shell config if needed:
 
 ```bash
-cabal install --installdir=$HOME/.local/bin
-```
+# For Stack
+export PATH="$HOME/.local/bin:$PATH"
 
-Make sure `~/.local/bin` is in your PATH. Add to your shell config if needed:
-
-```bash
+# For Cabal
 export PATH="$HOME/.local/bin:$PATH"
 ```
 
 ## Development
 
+```bash
+stack build    # compile
+stack test     # run tests
+stack repl     # interactive REPL
+```
+
 See [agents.md](agents.md) for information about the Claude Code agents used for Haskell refactoring in this project.
diff --git a/install-deps.sh b/install-deps.sh
index e3930c9..99c2a1d 100644
--- a/install-deps.sh
+++ b/install-deps.sh
@@ -1,2 +1,2 @@
 sudo apt update
-sudo apt install -y build-essential libgmp-dev libffi-dev zlib1g-dev texlive-latex-base texlive-fonts-recommended texlive-latex-extra texlive-xetex
+sudo apt install -y build-essential pkg-config libgmp-dev libffi-dev zlib1g-dev texlive-latex-base texlive-fonts-recommended texlive-latex-extra texlive-xetex