feat: add Makefile for contributor workflow

CONTRIBUTING.md

@@ -15,24 +15,27 @@
 git clone https://github.com/YOUR-USERNAME/Engram.git
 cd Engram
 
-# 2. Install
-./install.sh          # macOS / Linux
-# or: pip install -e ".[dev]"
+# 2. Install development dependencies
+make install
 
 # 3. Run the MCP server locally
-python -m engram.cli serve --http
+make serve
 
 # 4. Open the local dashboard
 # http://127.0.0.1:7474/dashboard
 
 # 5. Ask your agent (Claude Code, Cursor, etc.) to set up Engram
 # Your agent will call engram_init and you'll see it working.
 
-# 6. Make a change → open a PR
+# 6. Make a change and open a PR
 git checkout -b your-feature-or-fix
 ```
 
-That's it. If any step fails, open an issue — a broken setup path is itself a valid first contribution.
+That's it. If any step fails, open an issue - a broken setup path is itself a valid first contribution.
+
+Run `make help` to see every supported development command.
+
+If your machine has multiple Python installations, pass `PYTHON=/path/to/python` to keep install and test targets on the same interpreter.
 
 ---
 
@@ -101,6 +104,26 @@ Keep changes focused. One concern per PR. If you find yourself touching unrelate
 
 **4. Test your work**
 
+Before opening a PR, run the same local checks used by CI:
+
+```bash
+make check
+```
+
+For faster iteration, use the narrower targets:
+
+```bash
+make test
+make lint
+make format-check
+```
+
+To run one test file through the Makefile, pass `TEST_ARGS`:
+
+```bash
+make test TEST_ARGS="tests/test_cli_config.py -q"
+```
+
 Don't submit a PR you haven't run yourself. If tests don't exist yet for what you're changing, add them or note it clearly in the PR description.
 
 **5. Open a PR**
@@ -134,7 +157,7 @@ If you're unsure whether something is in scope, ask first. The cost of a quick d
 
 ## Code Style
 
-Consistency matters more than any particular style. Match what's already there. If you're introducing something new, be deliberate about it and note it in the PR.
+Consistency matters more than any particular style. Match what's already there. Use `make format` for automatic formatting and `make lint` before sending a PR. If you're introducing something new, be deliberate about it and note it in the PR.
 
 <br />
 

CONTRIBUTIONS.md

@@ -4,6 +4,18 @@ All changes are fully tested — the suite grows from the project's original tes
 
 ---
 
+## Round 9 - Makefile developer workflow
+
+**Summary:** Added a root `Makefile` as the canonical entry point for common contributor commands and updated contribution guidance to use it.
+
+**Files changed:** `Makefile`, `CONTRIBUTING.md`, `CONTRIBUTIONS.md`, `README.md`, `docs/DEVELOPER_SETUP.md`
+
+**Commands added:** `make help`, `make install`, `make test`, `make test-all`, `make lint`, `make format`, `make format-check`, `make check`, `make build`, `make clean`, `make serve`, `make docker-build`, `make docker-up`, `make docker-up-sqlite`, `make docker-up-postgres`, `make docker-down`, `make docker-logs`
+
+**New tests added:** 0 (developer workflow/documentation change)
+
+---
+
 ## Round 8 — Seven major features
 
 **Summary:** Implemented 7 production-ready features across the full stack (schema, storage, engine, REST, MCP, tests). Schema bumped from v7 to v8 with 5 new tables.

Makefile

@@ -0,0 +1,93 @@
+.DEFAULT_GOAL := help
+
+PYTHON ?= python
+PIP ?= $(PYTHON) -m pip
+PYTEST ?= $(PYTHON) -m pytest
+RUFF ?= $(PYTHON) -m ruff
+DOCKER_COMPOSE ?= docker compose
+TEST_ARGS ?= tests/ -x --tb=short
+TEST_ALL_ARGS ?= tests/
+
+export PYTHONPATH := src
+
+.PHONY: help install install-dev test test-all lint format format-check check build clean serve docker-build docker-up docker-up-sqlite docker-up-postgres docker-down docker-logs
+
+help:
+	@echo "Engram development commands"
+	@echo ""
+	@echo "Setup:"
+	@echo "  make install            Install Engram with development dependencies"
+	@echo "  make install-dev        Alias for make install"
+	@echo "                          Override Python with PYTHON=/path/to/python"
+	@echo ""
+	@echo "Quality:"
+	@echo "  make test               Run the CI-style pytest suite"
+	@echo "                          Override with TEST_ARGS='tests/test_file.py -q'"
+	@echo "  make test-all           Run the full pytest suite without fail-fast"
+	@echo "  make lint               Run ruff lint checks"
+	@echo "  make format             Format Python files with ruff"
+	@echo "  make format-check       Check formatting without modifying files"
+	@echo "  make check              Run lint, format-check, and tests"
+	@echo ""
+	@echo "Runtime:"
+	@echo "  make serve              Run the local HTTP MCP server"
+	@echo "  make build              Build Python package artifacts"
+	@echo "  make clean              Remove local build and Python cache artifacts"
+	@echo ""
+	@echo "Docker:"
+	@echo "  make docker-build       Build Docker images"
+	@echo "  make docker-up          Start the SQLite Docker profile"
+	@echo "  make docker-up-sqlite   Start the SQLite Docker profile"
+	@echo "  make docker-up-postgres Start the PostgreSQL Docker profile"
+	@echo "  make docker-down        Stop Docker Compose services"
+	@echo "  make docker-logs        Follow Docker Compose logs"
+
+install:
+	$(PIP) install --upgrade pip
+	$(PIP) install -e ".[dev]"
+
+install-dev: install
+
+test:
+	$(PYTEST) $(TEST_ARGS)
+
+test-all:
+	$(PYTEST) $(TEST_ALL_ARGS)
+
+lint:
+	$(RUFF) check .
+
+format:
+	$(RUFF) format .
+
+format-check:
+	$(RUFF) format --check .
+
+check: lint format-check test
+
+build:
+	$(PIP) install --upgrade build
+	$(PYTHON) -m build
+
+clean:
+	$(PYTHON) -c "import pathlib, shutil; targets=[pathlib.Path('.pytest_cache'), pathlib.Path('.ruff_cache'), pathlib.Path('build'), pathlib.Path('dist')]; targets += list(pathlib.Path('.').rglob('__pycache__')); targets += list(pathlib.Path('.').glob('*.egg-info')); [shutil.rmtree(path, ignore_errors=True) for path in targets]"
+
+serve:
+	$(PYTHON) -m engram.cli serve --http
+
+docker-build:
+	$(DOCKER_COMPOSE) --profile sqlite --profile postgres build
+
+docker-up: docker-up-sqlite
+
+docker-up-sqlite:
+	$(DOCKER_COMPOSE) --profile sqlite up --build
+
+docker-up-postgres:
+	$(DOCKER_COMPOSE) --profile postgres up --build
+
+docker-down:
+	$(DOCKER_COMPOSE) down
+
+docker-logs:
+	$(DOCKER_COMPOSE) logs -f

README.md

@@ -185,7 +185,7 @@ Full literature review: [`docs/LITERATURE.md`](./docs/LITERATURE.md)
 
 ## Contributing
 
-PRs welcome. See [`CONTRIBUTING.md`](./CONTRIBUTING.md) and [`HIRING.md`](./HIRING.md) for paid contract work ($125–185/hour).
+PRs welcome. Run `make help` for common development commands, then see [`CONTRIBUTING.md`](./CONTRIBUTING.md) and [`HIRING.md`](./HIRING.md) for paid contract work ($125–185/hour).
 
 ---