Add Makefile, GGUF_PATH override, and harden .gitignore

Makefile: thin wrapper over scripts/*. 'make help' lists targets
(build / smoke / check / hooks / clean). All variables (QUANT, PROFILE,
TAG, GGUF_PATH, MODEL) are overridable on the command line.

scripts/build.sh: honor GGUF_PATH so users with weights already on disk
(shared model dirs, NAS mounts, an Ollama blob copied out of
~/.ollama/models/blobs) don't have to copy or symlink. Also defers the
HF-CLI requirement until a download is actually needed.

.gitignore: exclude .cache/, *.incomplete, *.lock — running 'hf download'
inside the repo creates a .cache/huggingface/ tree, and a previous
session committed an empty version of it. Belt-and-suspenders.

README + CHANGELOG updated to reflect the new flow.

.gitignore

@@ -10,8 +10,15 @@ venv/
 *.safetensors
 *.bin
 
+# Build / runtime artifacts that get created if anyone runs hf download or
+# scripts/build.sh from inside the repo.
+.cache/
+*.incomplete
+*.lock
+
 # Editor / OS
 .DS_Store
 .idea/
 .vscode/
 *.swp
+*~

CHANGELOG.md

@@ -7,13 +7,29 @@ and documentation**, not the underlying base model.
 
 ## [Unreleased]
 
+### Added
+- `Makefile` — convenience wrapper. `make help` lists targets:
+  `build` / `smoke` / `check` / `hooks` / `clean`. Variables
+  `QUANT`, `PROFILE`, `TAG`, `GGUF_PATH`, `MODEL` are overridable.
+
+### Changed
+- `scripts/build.sh` now honors `GGUF_PATH` so users with weights already
+  on disk (e.g. shared model dirs, NAS mounts) don't have to download or
+  symlink. Also defers the HF-CLI requirement until a download is
+  actually needed.
+- `.gitignore` now excludes `.cache/`, `*.incomplete`, and `*.lock` so
+  ephemeral artifacts from running `hf download` inside the repo never
+  get committed.
+
+## [0.3.0] - 2026-05-02 — `7766f0b`
+
 ### Added
 - `scripts/check.sh` — local lint runner: `bash -n`, optional `shellcheck`,
   `pyflakes`, `py_compile`, plus a guard regex for the dash/dot filename
   bug. Returns non-zero on failure.
 - `scripts/install-hooks.sh` — installs `check.sh` as a git pre-commit
   hook so footguns can't slip past again.
-- `CHANGELOG.md` (this file).
+- `CHANGELOG.md`.
 
 ## [0.2.1] - 2026-05-02 — `82677d0`
 

Makefile

@@ -0,0 +1,61 @@
+# Janus-27B convenience Makefile.
+#
+# All work is delegated to scripts/* — this file just gives common
+# operations short, discoverable names.
+#
+# Variables you can override on the command line:
+#   QUANT     GGUF quant suffix       (default: Q4_K_M)
+#   PROFILE   default | z13           (default: default)
+#   TAG       Ollama model tag        (auto: janus-27b or janus-27b-z13)
+#   GGUF_PATH path to existing GGUF   (skip the download)
+#   MODEL     model tag for smoke     (default: $(TAG))
+#
+# Examples:
+#   make build                          # default profile, Q4_K_M
+#   make build PROFILE=z13 QUANT=Q3_K_S
+#   make build GGUF_PATH=~/models/Qwen3.6-27B-Q4_K_M.gguf
+#   make smoke
+#   make check
+#   make clean
+
+QUANT   ?= Q4_K_M
+PROFILE ?= default
+
+ifeq ($(PROFILE),z13)
+    TAG ?= janus-27b-z13
+else
+    TAG ?= janus-27b
+endif
+
+MODEL ?= $(TAG)
+
+.DEFAULT_GOAL := help
+
+.PHONY: help build smoke check hooks clean
+
+help:  ## Show this help.
+	@awk 'BEGIN {FS = ":.*##"; printf "Targets:\n"} /^[a-zA-Z_-]+:.*?##/ { printf "  \033[36m%-12s\033[0m %s\n", $$1, $$2 }' $(MAKEFILE_LIST)
+	@echo
+	@echo "Current settings:"
+	@echo "  QUANT=$(QUANT) PROFILE=$(PROFILE) TAG=$(TAG)"
+ifdef GGUF_PATH
+	@echo "  GGUF_PATH=$(GGUF_PATH)"
+endif
+
+build:  ## Download GGUF (if needed) and run 'ollama create'.
+	GGUF_PATH=$(GGUF_PATH) ./scripts/build.sh $(QUANT) $(PROFILE)
+
+smoke:  ## Verify the model is reachable and round-trips.
+	MODEL=$(MODEL) ./scripts/smoke_test.sh
+
+check:  ## Lint shell + python files; block dot-pattern footgun.
+	./scripts/check.sh
+
+hooks:  ## Install scripts/check.sh as the git pre-commit hook.
+	./scripts/install-hooks.sh
+
+clean:  ## Remove local GGUF copies and ephemeral caches in this repo.
+	@echo "[*] removing local GGUFs and ephemeral caches in $$PWD"
+	@rm -f ./Qwen3.6-27B-*.gguf
+	@rm -rf ./.cache __pycache__ examples/__pycache__
+	@echo "[+] clean"

README.md

@@ -89,6 +89,7 @@ The 27B is **dense**: every parameter participates in every forward pass. It's s
 | `scripts/smoke_test.sh` | Verifies an Ollama daemon + model and runs a round-trip |
 | `scripts/check.sh` | Local lint: `bash -n`, `pyflakes`, `py_compile`, footgun-grep |
 | `scripts/install-hooks.sh` | Installs `check.sh` as a git pre-commit hook |
+| `Makefile` | Convenience wrapper — `make help` lists targets |
 | `LICENSE`, `CITATION.cff` | Apache-2.0 license and citation metadata |
 | `CHANGELOG.md` | Versioned tooling/docs changes |
 | `README.md` | This file |
@@ -113,25 +114,24 @@ If you want the safetensors for `transformers`, fetch them from [`Qwen/Qwen3.6-2
 
 ### Ollama (one-liner)
 
-`scripts/build.sh` will download the GGUF and create the Ollama model in one shot:
-
 ```bash
-./scripts/build.sh                  # Q4_K_M, default profile      -> janus-27b
-./scripts/build.sh Q3_K_S z13       # Z13 profile (Modelfile.z13)  -> janus-27b-z13
-./scripts/build.sh Q5_K_M           # higher-quality quant         -> janus-27b
+make build                                  # Q4_K_M, default profile     -> janus-27b
+make build PROFILE=z13 QUANT=Q3_K_S         # Z13 profile (Modelfile.z13) -> janus-27b-z13
+make build GGUF_PATH=~/models/Qwen3.6-27B-Q4_K_M.gguf   # skip download
 ollama run janus-27b
 ```
 
-Or do it manually if you already have a GGUF on disk — edit the `FROM` line in `Modelfile` and run:
+Under the hood, `make build` calls `scripts/build.sh`, which downloads the
+GGUF if missing (set `GGUF_PATH` to point at one you already have) and
+runs `ollama create` with the matching `Modelfile`.
 
-```bash
-ollama create janus-27b -f Modelfile && ollama run janus-27b
-```
+If you'd rather do it by hand: edit the `FROM` line in `Modelfile` and
+run `ollama create janus-27b -f Modelfile && ollama run janus-27b`.
 
 Confirm everything works:
 
 ```bash
-./scripts/smoke_test.sh             # checks server, model, round-trip
+make smoke                          # checks server, model, round-trip
 python examples/ollama_chat.py      # full demo: chat, streaming, tools, OpenAI-compat
 ```
 

scripts/build.sh

@@ -7,7 +7,10 @@
 #   ./scripts/build.sh Q3_K_S z13            # quant + Z13 profile (uses Modelfile.z13)
 #   QUANT=Q6_K PROFILE=default ./scripts/build.sh
 #
-# Requires: huggingface-cli (or hf), ollama, awk, sed.
+# Skip the download by pointing at a GGUF you already have:
+#   GGUF_PATH=/path/to/Qwen3.6-27B-Q4_K_M.gguf ./scripts/build.sh Q4_K_M
+#
+# Requires: huggingface-cli (or hf), ollama, awk.
 set -euo pipefail
 
 QUANT="${1:-${QUANT:-Q4_K_M}}"
@@ -22,7 +25,9 @@ REPO_ID="${REPO_ID:-unsloth/Qwen3.6-27B-GGUF}"
 #   UD-Q5_K_XL UD-Q6_K_XL UD-Q8_K_XL
 GGUF_NAME="Qwen3.6-27B-${QUANT}.gguf"
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
-GGUF_PATH="${ROOT}/${GGUF_NAME}"
+# GGUF_PATH defaults to ${ROOT}/${GGUF_NAME}, but can be overridden so users
+# with cached weights elsewhere don't have to copy or symlink anything.
+GGUF_PATH="${GGUF_PATH:-${ROOT}/${GGUF_NAME}}"
 
 case "${PROFILE}" in
     default) MODELFILE="${ROOT}/Modelfile";        TAG="janus-27b" ;;
@@ -46,33 +51,38 @@ if [[ ! -f "${MODELFILE}" ]]; then
     echo "[!] Missing ${MODELFILE}" >&2; exit 1
 fi
 
-# ---- 2. Pick a HuggingFace CLI ----------------------------------------------
-
-HF=""
-if command -v hf >/dev/null 2>&1; then
-    HF="hf"
-elif command -v huggingface-cli >/dev/null 2>&1; then
-    HF="huggingface-cli"
-else
-    echo "[!] Neither 'hf' nor 'huggingface-cli' found." >&2
-    echo "    pip install -U huggingface_hub" >&2
-    exit 1
-fi
-
-# ---- 3. Download GGUF if missing --------------------------------------------
+# ---- 2. Download GGUF if missing --------------------------------------------
 
 if [[ -f "${GGUF_PATH}" ]]; then
-    echo "[=] GGUF already present, skipping download."
+    echo "[=] GGUF already present at ${GGUF_PATH}, skipping download."
 else
+    # Need a HF CLI to fetch the file.
+    HF=""
+    if command -v hf >/dev/null 2>&1; then
+        HF="hf"
+    elif command -v huggingface-cli >/dev/null 2>&1; then
+        HF="huggingface-cli"
+    else
+        echo "[!] ${GGUF_PATH} not found, and neither 'hf' nor" >&2
+        echo "    'huggingface-cli' is installed to download it." >&2
+        echo "    Either:" >&2
+        echo "      pip install -U huggingface_hub" >&2
+        echo "    or set GGUF_PATH to an existing GGUF and rerun." >&2
+        exit 1
+    fi
+
     echo "[*] Downloading ${GGUF_NAME} from ${REPO_ID} ..."
+    DEST_DIR="$(dirname "${GGUF_PATH}")"
+    mkdir -p "${DEST_DIR}"
     case "${HF}" in
-        hf)                 hf download "${REPO_ID}" "${GGUF_NAME}" --local-dir "${ROOT}" ;;
-        huggingface-cli)    huggingface-cli download "${REPO_ID}" "${GGUF_NAME}" --local-dir "${ROOT}" ;;
+        hf)              hf download "${REPO_ID}" "${GGUF_NAME}" --local-dir "${DEST_DIR}" ;;
+        huggingface-cli) huggingface-cli download "${REPO_ID}" "${GGUF_NAME}" --local-dir "${DEST_DIR}" ;;
     esac
 fi
 
 if [[ ! -f "${GGUF_PATH}" ]]; then
-    echo "[!] Download failed: ${GGUF_PATH} not present." >&2; exit 1
+    echo "[!] GGUF still not present at ${GGUF_PATH} after download attempt." >&2
+    exit 1
 fi
 
 # ---- 4. Patch the Modelfile FROM line in a temp copy -------------------------