diff --git a/Makefile b/Makefile
index 2a16a1091a..399bffb8a1 100644
--- a/Makefile
+++ b/Makefile
@@ -57,6 +57,9 @@ SERVICE_PORT_FLAG := $(if $(PORT),--port $(PORT),)
 SERVICE_HOME_DIR_FLAG := $(if $(HOME_DIR),--home-dir "$(HOME_DIR)",)
 SERVICE_NO_BOOT_START_FLAG := $(if $(filter 1 true yes,$(NO_BOOT_START)),--no-boot-start,)
 SERVICE_INSTALL_FLAGS := $(SERVICE_PORT_FLAG) $(SERVICE_HOME_DIR_FLAG) $(SERVICE_NO_BOOT_START_FLAG)
+DEV_PORT_FLAG := $(if $(PORT),--port $(PORT),)
+DEV_WEB_PORT_FLAG := $(if $(WEB_PORT),--web-internal-port $(WEB_PORT),)
+DEV_FLAGS := $(DEV_PORT_FLAG) $(DEV_WEB_PORT_FLAG) $(DEV_ARGS)
 DESKTOP_BUNDLES ?= dmg
 
 # Phase headers
@@ -84,6 +87,7 @@ help:
 	@echo "  bootstrap        Install mise tools, workspace deps, and git hooks"
 	@echo "  bootstrap-e2e    Bootstrap plus Playwright browser/system deps"
 	@echo "  dev              Run backend + web via local CLI (auto ports)"
+	@echo "  dev PORT=38430   Run dev on a fixed backend port (beats KANDEV_BACKEND_PORT)"
 	@echo "  dev-prod-db      Run dev mode against the production db at ~/.kandev"
 	@echo "  dev-backend      Run backend in development mode (port 38429)"
 	@echo "  dev-web          Run web app in development mode (port 37429)"
@@ -188,7 +192,7 @@ ifeq ($(OS),Windows_NT)
 	@$(MAKE) -C $(BACKEND_DIR) build-winjob
 endif
 	@echo "Launching via CLI (auto ports)..."
-	@cd $(APPS_DIR) && $(PNPM) -C cli dev -- dev
+	@cd $(APPS_DIR) && $(PNPM) -C cli dev -- dev $(DEV_FLAGS)
 
 .PHONY: dev-prod-db
 dev-prod-db: export KANDEV_DATABASE_PATH := $(HOME)/.kandev/data/kandev.db
diff --git a/docs/public/contributing.md b/docs/public/contributing.md
index 526fc9b542..abd03d59a2 100644
--- a/docs/public/contributing.md
+++ b/docs/public/contributing.md
@@ -34,6 +34,12 @@ make dev
 
 This is the normal development path. The TypeScript supervisor starts the Go backend and Vite, selects available ports, points Go at Vite, and isolates application state under the checkout's `.kandev-dev/`. Use the printed URLs. Backend logs append to `.kandev-dev/logs/backend-logs.log`; startup prints the resolved path.
 
+Automatic port selection only applies when no port was requested, and `KANDEV_BACKEND_PORT` or `KANDEV_PORT` in the environment counts as a request. An installed Kandev service that exported one therefore pins development mode to the port its own backend already occupies, and the development backend fails to listen. Pass `PORT=` to override both the environment and the automatic choice, `WEB_PORT=` for the internal Vite port, and `DEV_ARGS=` for any other launcher flag.
+
+```bash
+make dev PORT=38430 WEB_PORT=37430
+```
+
 `make dev-web` starts only Vite on its fixed development port; it has no live API by itself. `make dev-backend` starts only the backend with the normal production-profile home unless you override it. For an intentionally isolated backend-only run:
 
 ```bash