From 0949ee671a10b220a355fccbcd8a31f78d4e74e6 Mon Sep 17 00:00:00 2001
From: Jeremy Eder <jeder@redhat.com>
Date: Thu, 8 Jan 2026 11:08:51 -0500
Subject: [PATCH] docs: add development setup instructions

- Add Development Setup section to README.md with prerequisites
- Update setup.sh to install pre-commit hooks automatically
- Add npm tool checks (markdownlint, mermaid-cli) to setup.sh
- Simplify next steps in setup.sh output
---
 README.md        | 16 ++++++++++++++++
 scripts/setup.sh | 28 +++++++++++++++++++++-------
 2 files changed, 37 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index d427932..9ef2437 100644
--- a/README.md
+++ b/README.md
@@ -19,6 +19,22 @@ AI-assisted development patterns. Each pattern is standalone - adopt what you ne
 
 See [Quickstart](docs/quickstart.md) for pattern overview and adoption guidance.
 
+## Development Setup
+
+```bash
+git clone https://github.com/ambient-code/reference.git
+cd reference
+./scripts/setup.sh
+source .venv/bin/activate
+pre-commit install
+```
+
+**Prerequisites**: Python 3.11+, Node.js (for markdownlint and mermaid-cli)
+
+```bash
+npm install -g markdownlint-cli @mermaid-js/mermaid-cli
+```
+
 ## Repository Contents
 
 ```text
diff --git a/scripts/setup.sh b/scripts/setup.sh
index 5ebe953..bbdffaf 100755
--- a/scripts/setup.sh
+++ b/scripts/setup.sh
@@ -27,18 +27,32 @@ fi
 echo "Installing documentation dependencies..."
 uv pip install -r requirements-dev.txt
 
-# Verify installation
-echo "Verifying installation..."
-echo "✓ Documentation tooling installed"
+# Install pre-commit hooks
+echo "Installing pre-commit hooks..."
+.venv/bin/pre-commit install
 
+# Check for npm tools
 echo ""
-echo "Setup complete! 🎉"
+echo "Checking npm tools..."
+if command -v markdownlint &> /dev/null; then
+    echo "✓ markdownlint installed"
+else
+    echo "⚠ markdownlint not found - install with: npm install -g markdownlint-cli"
+fi
+
+if command -v mmdc &> /dev/null; then
+    echo "✓ mermaid-cli installed"
+else
+    echo "⚠ mermaid-cli not found - install with: npm install -g @mermaid-js/mermaid-cli"
+fi
+
+echo ""
+echo "Setup complete!"
 echo ""
 echo "Next steps:"
 echo "  1. Activate virtual environment: source .venv/bin/activate"
-echo "  2. Explore documentation: cat docs/quickstart.md"
-echo "  3. Validate Mermaid diagrams: ./scripts/validate-mermaid.sh"
-echo "  4. Lint markdown: markdownlint docs/**/*.md --fix"
+echo "  2. Install npm tools (if missing): npm install -g markdownlint-cli @mermaid-js/mermaid-cli"
+echo "  3. Validate docs: pre-commit run --all-files"
 echo ""
 echo "For a working application demo, see:"
 echo "  https://github.com/ambient-code/demo-fastapi"