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

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
+# Install (Makefile shortcut — creates .venv and installs deps)
-pip install -e .
+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?"