From 9ecc1db38d4437c0baa107d51a80f4991ed6fec0 Mon Sep 17 00:00:00 2001
From: Jeff Smith <jeff@unbiasedgeek.com>
Date: Wed, 8 Apr 2026 16:31:00 -0600
Subject: [PATCH] chore: add Makefile with venv-based dev workflow

Targets:
  make install      create .venv and pip install -e ".[dev]"
  make test         pytest inside the venv
  make test-cov     pytest with coverage
  make lint         ruff + black --check
  make ask          run a sample research call
  make costs        show the cost ledger
  make clean        remove venv and caches
  make docker-build / docker-test   parity wrappers for the docker flow

Lets contributors get from clone to running CLI in one command
without depending on docker. README points at make install as
the recommended path; manual venv steps documented as fallback.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 Makefile  | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 README.md |  6 ++++--
 2 files changed, 59 insertions(+), 2 deletions(-)
 create mode 100644 Makefile

diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..fec314a
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,55 @@
+# Marchwarden development tasks.
+#
+# All venv targets create/use ./.venv. Targets that need to invoke
+# python from inside the venv use $(VENV_PY) so they work whether or
+# not the venv is currently activated in the shell.
+
+VENV       := .venv
+VENV_PY    := $(VENV)/bin/python
+VENV_PIP   := $(VENV)/bin/pip
+VENV_BIN   := $(VENV)/bin
+
+PYTHON ?= python3
+
+.DEFAULT_GOAL := help
+
+.PHONY: help venv install test test-cov lint clean ask costs docker-build docker-test
+
+help:  ## Show this help.
+	@awk 'BEGIN {FS = ":.*##"; printf "Marchwarden — make targets\n\n"} /^[a-zA-Z_-]+:.*?##/ { printf "  \033[36m%-15s\033[0m %s\n", $$1, $$2 }' $(MAKEFILE_LIST)
+
+venv: $(VENV_PY)  ## Create the .venv if it doesn't exist.
+
+$(VENV_PY):
+	$(PYTHON) -m venv $(VENV)
+	$(VENV_PIP) install --upgrade pip
+
+install: venv  ## Install the project editable with dev extras into .venv.
+	$(VENV_PIP) install -e ".[dev]"
+
+test: install  ## Run the test suite inside the venv.
+	$(VENV_BIN)/pytest -q
+
+test-cov: install  ## Run tests with coverage.
+	$(VENV_BIN)/pytest --cov=cli --cov=obs --cov=researchers --cov-report=term-missing
+
+lint: install  ## Run ruff and black --check.
+	$(VENV_BIN)/ruff check .
+	$(VENV_BIN)/black --check .
+
+ask: install  ## Run a sample research call. Override Q="..." to ask something else.
+	$(VENV_BIN)/marchwarden ask "$${Q:-What is the highest peak in Utah?}" --depth shallow
+
+costs: install  ## Show the cost ledger summary.
+	$(VENV_BIN)/marchwarden costs
+
+clean:  ## Remove the venv and Python caches.
+	rm -rf $(VENV) .pytest_cache .ruff_cache .mypy_cache .coverage htmlcov
+	find . -type d -name __pycache__ -prune -exec rm -rf {} +
+	find . -type d -name "*.egg-info" -prune -exec rm -rf {} +
+
+docker-build:  ## Build the docker test image.
+	./scripts/docker-test.sh build
+
+docker-test:  ## Run the test suite inside docker.
+	./scripts/docker-test.sh test
diff --git a/README.md b/README.md
index b5ac669..14a3227 100644
--- a/README.md
+++ b/README.md
@@ -14,8 +14,10 @@ Marchwarden researchers are stationed at the frontier of knowledge — they watc
 git clone https://forgejo.labbity.unbiasedgeek.com/archeious/marchwarden.git
 cd marchwarden
 
-# Install
-pip install -e .
+# Install (Makefile shortcut — creates .venv and installs deps)
+make install
+# or manually:
+python3 -m venv .venv && source .venv/bin/activate && pip install -e ".[dev]"
 
 # Ask a question
 marchwarden ask "What are ideal crops for a garden in Utah?"