chore: align engineering configuration and CI entry points

Author: xxg1413

.gitattributes

@@ -0,0 +1,3 @@
+# Stable LF checkouts keep generated JSON, source checksums and solution hashes
+# identical across contributor platforms, independent of core.autocrlf.
+* text=auto eol=lf

.github/workflows/validate.yml

@@ -1,6 +1,7 @@
 name: Validate
 
 on:
+  workflow_dispatch:
   pull_request:
   push:
     branches:
@@ -11,7 +12,8 @@ permissions:
 
 concurrency:
   group: validate-${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
+  # Preserve a complete default-branch validation; superseded PR runs can stop.
+  cancel-in-progress: ${{ github.ref != 'refs/heads/master' }}
 
 jobs:
   # Lowest and latest supported CPython; the universal lock already resolves

AGENTS.md

@@ -76,6 +76,16 @@ reviewed catalog data, and stable public JSON contracts.
 - After merge, verify the immutable raw `catalog.json`. Verify flypython.com only
   after a separate, deliberate consumer-version update.
 
+## Engineering entry points
+
+- `make help` lists the existing validation and generation tools.
+- `make setup` installs the locked dev environment; use
+  `make check PYTHON=.venv/bin/python` afterwards.
+- `make generated-check` is read-only; `make generate` rewrites derived content
+  in dependency order. Neither publishes or changes the website content pin.
+- Keep agent rules here; `CLAUDE.md` imports this file rather than copying it.
+- Engineering configuration rationale is in `docs/ENGINEERING_CONFIG.md`.
+
 ## Review priorities
 
 1. Content accuracy and source quality.

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

CONTRIBUTING.md

@@ -84,6 +84,18 @@ and path folders that ship their own `requirements.txt` must pin exactly the
 versions in `requirements-dev.lock.txt` (`tests/test_dependency_pins.py`), so
 CI tests the stack learners install.
 
+With `uv` installed, `make setup` is an alternative to the manual setup above:
+it uses `.python-version` and synchronizes the exact dev lock into `.venv`.
+Then use `make check PYTHON=.venv/bin/python`; Make otherwise defaults to
+`python3`. The Make aliases assume a POSIX shell (Windows contributors can use
+the direct Python commands below or WSL). Run from this repository or use
+`make -C path/to/python`, not `make -f path/to/Makefile` from another directory.
+
+`make generated-check` checks derived content without rewriting it, including
+course solution hashes. `make generate` regenerates exports, README indexes,
+the content manifest and solution hashes in order; `make all` then runs checks.
+Both preserve ordering even when invoked with `make -j`.
+
 After changing catalog sources, regenerate the public export:
 
 ```bash
@@ -101,6 +113,7 @@ python tools/validate_catalog.py
 python tools/export_catalog.py --check --target both
 python tools/render_readmes.py --check
 python tools/build_content_manifest.py --check
+python tools/build_solution_hashes.py --check
 python tools/verify_examples.py
 python tools/verify_courses.py
 python tools/verify_paths.py

Makefile

@@ -1,4 +1,11 @@
-.PHONY: help check export render manifest test verify courses paths lint lock lock-check all
+# Recipes use repository-relative paths. Like Magpie's Makefile, fail closed
+# when invoked with `make -f path/to/Makefile` from an unrelated directory.
+ifeq ($(and $(wildcard pyproject.toml),$(wildcard tools/validate_catalog.py),$(wildcard catalog/catalog.yml)),)
+  $(error run make in the Python repository (make -C path/to/python))
+endif
+
+.DEFAULT_GOAL := help
+.PHONY: help setup check generated-check generate export render manifest solutions test verify courses paths lint lock lock-check all
 
 PYTHON ?= python3
 UV ?= uv
@@ -15,10 +22,14 @@ endef
 
 help:
 	@echo "FlyPython Development Workflow:"
-	@echo "  make check      - Run the same checks as CI: lint, tests, catalog, radar, export, readme, manifest, example, course, and path checks"
+	@echo "  make setup      - Create .venv using .python-version and install locked dev dependencies (requires uv)"
+	@echo "  make check      - Run CI checks (use PYTHON=.venv/bin/python after setup)"
+	@echo "  make generated-check - Check catalog, exports, READMEs, manifest, and solution hashes without rewriting"
+	@echo "  make generate   - Regenerate all derived content in dependency order"
 	@echo "  make export     - Regenerate catalog.json and radar.json"
 	@echo "  make render     - Regenerate root and catalog README indexes plus the Radar table"
 	@echo "  make manifest   - Regenerate content-manifest.json"
+	@echo "  make solutions  - Regenerate course-solutions.json"
 	@echo "  make lint       - Run ruff"
 	@echo "  make test       - Run pytest test suite"
 	@echo "  make verify     - Verify all runnable examples"
@@ -28,14 +39,29 @@ help:
 	@echo "  make lock-check - Fail if the lock files no longer match pyproject.toml"
 	@echo "  make all        - Regenerate all exports and run all checks and tests"
 
-check: lint test
+setup:
+	$(UV) venv --python "$$(cat .python-version)" .venv
+	$(UV) pip sync --python .venv/bin/python requirements-dev.lock.txt
+
+check: lint test generated-check
+	$(PYTHON) tools/verify_examples.py
+	$(PYTHON) tools/verify_courses.py
+	$(PYTHON) tools/verify_paths.py
+
+generated-check:
 	$(PYTHON) tools/validate_catalog.py
 	$(PYTHON) tools/export_catalog.py --check --target both
 	$(PYTHON) tools/render_readmes.py --check
 	$(PYTHON) tools/build_content_manifest.py --check
-	$(PYTHON) tools/verify_examples.py
-	$(PYTHON) tools/verify_courses.py
-	$(PYTHON) tools/verify_paths.py
+	$(PYTHON) tools/build_solution_hashes.py --check
+
+# Keep writers sequential even under make -j: README/manifest checks must not
+# race against a producer. No automatic commit, content-pin update or deploy.
+generate:
+	$(MAKE) export
+	$(MAKE) render
+	$(MAKE) manifest
+	$(MAKE) solutions
 
 export:
 	$(PYTHON) tools/export_catalog.py --target both
@@ -46,6 +72,9 @@ render:
 manifest:
 	$(PYTHON) tools/build_content_manifest.py
 
+solutions:
+	$(PYTHON) tools/build_solution_hashes.py
+
 lint:
 	$(PYTHON) -m ruff check .
 
@@ -72,4 +101,5 @@ lock-check:
 	@git diff --exit-code requirements.lock.txt requirements-dev.lock.txt || \
 		{ echo "lock files drifted from pyproject.toml — commit the regenerated files"; exit 1; }
 
-all: export render manifest check
+all: generate
+	$(MAKE) check

docs/ENGINEERING_CONFIG.md

@@ -0,0 +1,43 @@
+# Engineering configuration
+
+The Python repository already has a locked Python toolchain, a Makefile,
+SHA-pinned GitHub Actions and deterministic bilingual-content gates. These remain
+the source of truth. The configuration additions reference
+[yetone/magpie](https://github.com/yetone/magpie) (reviewed 2026-10-22), adapting
+its engineering practices rather than its Go/desktop stack.
+
+| Reference | FlyPython adaptation |
+| --- | --- |
+| [Makefile](https://github.com/yetone/magpie/blob/main/Makefile) | Guard repository-relative recipes against the wrong working directory; extend the existing command entry point rather than add another task runner. |
+| [.gitattributes](https://github.com/yetone/magpie/blob/main/.gitattributes) | Force LF for text checkouts, keeping source checksums and generated output stable across platforms. Binary files remain auto-detected. |
+| [CLAUDE.md](https://github.com/yetone/magpie/blob/main/CLAUDE.md) | Import the existing AGENTS.md; do not maintain two copies of the same agent rules. |
+| [test workflow](https://github.com/yetone/magpie/blob/main/.github/workflows/test.yml) | Allow manual validation; do not cancel an in-progress default-branch run on every new push, while superseded PR runs are canceled. |
+
+## Local commands
+
+Use a POSIX shell and `make` from this repository (or `make -C path/to/python`).
+`make setup` requires uv, selects `.python-version`, and syncs
+`requirements-dev.lock.txt` into `.venv`. It does not update dependency locks.
+Use `make check PYTHON=.venv/bin/python` after setup; the Make default remains
+`python3` so existing CI and activated environments keep working. Native Windows
+contributors can run the direct Python commands in CONTRIBUTING.md or use WSL.
+
+`make generated-check` runs validation and read-only checks of catalog/radar,
+README sections, content manifest and course solution hashes. `make generate`
+regenerates those artifacts sequentially; `make all` regenerates, then checks.
+The ordering holds under `make -j` too. No target publishes content or deploys.
+
+## Intentionally not copied
+
+- Go, Bun, GTK/WebKit, native binary packaging and Docker publishing do not fit
+  this content-and-Python-tools repository.
+- No automatic website pin update, release or production deployment is added.
+- Existing exact locks, CI Python version matrix, least-privilege permissions,
+  SHA-pinned actions and job timeout remain intact.
+- No mass formatting or line-ending renormalization is performed. If a future
+  byte-sensitive fixture deliberately needs CRLF, add a narrow per-file
+  attributes exception; do not disable LF for ordinary source files.
+
+Configuration regression tests verify the thin agent entry point, wrong-directory
+Make guard, locked setup command, read-only generated checks and parallel-safe
+regeneration ordering. They run in the existing pytest/CI suite.

tests/test_engineering_config.py

@@ -0,0 +1,49 @@
+"""Keep developer entry points safe and aligned with generated-content gates."""
+
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def _make(*args: str, cwd: Path = ROOT) -> subprocess.CompletedProcess[str]:
+    if not shutil.which("make"):
+        pytest.skip("GNU/POSIX make is not installed")
+    return subprocess.run(
+        ["make", *args], cwd=cwd, capture_output=True, text=True, timeout=15,
+        check=False,
+    )
+
+
+def test_agent_entrypoint_has_single_source() -> None:
+    assert (ROOT / "CLAUDE.md").read_text().strip() == "@AGENTS.md"
+    assert "* text=auto eol=lf" in (ROOT / ".gitattributes").read_text()
+
+
+def test_make_rejects_unrelated_working_directory(tmp_path: Path) -> None:
+    result = _make("-f", str(ROOT / "Makefile"), "-n", "setup", cwd=tmp_path)
+    assert result.returncode != 0
+    assert "run make in the Python repository" in result.stderr
+
+
+def test_make_generated_checks_are_read_only_and_include_solution_hashes() -> None:
+    result = _make("-n", "generated-check")
+    assert result.returncode == 0, result.stderr
+    for name in ("export_catalog", "render_readmes", "build_content_manifest", "build_solution_hashes"):
+        assert f"tools/{name}.py --check" in result.stdout
+
+
+def test_make_setup_uses_pinned_interpreter_and_locked_dependencies() -> None:
+    result = _make("-n", "setup")
+    assert result.returncode == 0, result.stderr
+    assert ".python-version" in result.stdout
+    assert "pip sync --python .venv/bin/python requirements-dev.lock.txt" in result.stdout
+
+
+def test_make_all_regenerates_before_checks_even_in_parallel() -> None:
+    result = _make("-n", "-j4", "all")
+    assert result.returncode == 0, result.stderr
+    assert result.stdout.index("tools/build_solution_hashes.py\n") < result.stdout.index("-m ruff check .")