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

@@ -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?"