Dev setup: Windows-first (most devs are on VS Code / Windows)

PowerShell commands lead, bash equivalents in comments: venv
Activate.ps1 + execution-policy note, copy/$env:, a PowerShell
plugin-enable loop, and how the bash naming hook runs under Git Bash
(plus the pre-commit hook catching it automatically). The VS Code
Check task gets a Windows variant (venv\Scripts, bash for the .sh).
Pin shell scripts to LF in .gitattributes so a Windows checkout does
not CRLF-corrupt them into 'bad interpreter' failures.

.gitattributes

@@ -1 +1,5 @@
 .env filter=git-crypt diff=git-crypt
+
+# Shell scripts must stay LF so Git Bash on Windows can run them
+*.sh text eol=lf
+scripts/check-naming-and-style.sh text eol=lf

.vscode/tasks.json

@@ -36,6 +36,9 @@
       "label": "Check: naming + tests + build",
       "type": "shell",
       "command": "bash scripts/check-naming-and-style.sh && venv/bin/python -m pytest tests/ -q && cd frontend && npx vitest run && npm run build",
+      "windows": {
+        "command": "bash scripts/check-naming-and-style.sh && venv\\Scripts\\python -m pytest tests/ -q && cd frontend && npx vitest run && npm run build"
+      },
       "options": { "cwd": "${workspaceFolder}" },
       "problemMatcher": []
     }

docs/DEVELOPMENT-SETUP.md

@@ -6,11 +6,16 @@ material lives elsewhere - naming rules in `CONTRIBUTING.md`, every config
 variable in the CONFIG guide, plugin authoring in the PLUGIN docs - this is
 just the on-ramp.
 
-Two ways to run it. **Docker** is the fastest to a working site (one command
-brings up MySQL + the app). **Manual (venv + Node)** is what most people
-iterate with, because the frontend hot-reloads and the backend restarts on
-save. Do Docker first to confirm the box is sane, then switch to manual for
-day-to-day work - or go straight to manual if you already have a MySQL.
+**Most developers here are on Windows in VS Code** - commands below are
+PowerShell first, with the bash equivalent in a comment where they differ.
+Install **Git for Windows** (it ships Git Bash, which VS Code and the git
+hooks use to run the shell-based naming check) and **VS Code** with the
+extensions this repo recommends (you'll be prompted - section 2c).
+
+Two ways to run it. **Docker** (Docker Desktop on Windows) is the fastest to a
+working site. **Manual (venv + Node)** is the daily driver - frontend
+hot-reloads, backend restarts on save. Do Docker once to confirm the box is
+sane, then use manual for day-to-day work.
 
 ---
 
@@ -86,17 +91,19 @@ FLUSH PRIVILEGES;
 
 ### Backend
 
-```bash
+```powershell
 python -m venv venv
-source venv/bin/activate               # Windows: venv\Scripts\activate
+venv\Scripts\Activate.ps1             # bash/mac: source venv/bin/activate
+# If PowerShell blocks the activate script (execution policy), run once:
+#   Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
 pip install -r requirements.txt
 
-cp .env.example .env
-# Set SECRET_KEY, JWT_SECRET_KEY, and
+copy .env.example .env                 # bash/mac: cp .env.example .env
+# Edit .env - set SECRET_KEY, JWT_SECRET_KEY, and
 #   DATABASE_URL=mysql+pymysql://shopdb:devpassword@127.0.0.1:3306/shopdb_flask?charset=utf8mb4
 #   CORS_ORIGINS=http://localhost:5173
 
-export FLASK_APP=shopdb
+$env:FLASK_APP = "shopdb"              # bash/mac: export FLASK_APP=shopdb
 flask db upgrade                       # core schema
 flask plugin upgrade-all               # per-plugin schema (ADR-008)
 flask seed permissions
@@ -108,13 +115,18 @@ flask seed admin --username admin --email you@example.com   # password printed o
 Enable the plugins you want visible (they install on a fresh box; some ship
 disabled). To turn on everything for development:
 
-```bash
-for p in computers employees machines measuringtools network notifications \
-         printers slides usb warranty knowledgebase geenforce printedparts; do
-  flask plugin install "$p"; flask plugin enable "$p"
-done
+PowerShell:
+
+```powershell
+foreach ($p in "computers","employees","machines","measuringtools","network",
+               "notifications","printers","slides","usb","warranty",
+               "knowledgebase","geenforce","printedparts") {
+  flask plugin install $p; flask plugin enable $p
+}
 ```
 
+(bash/mac: a `for p in ...; do flask plugin install "$p"; ...; done` loop.)
+
 Run the backend ON PORT 5001 - the frontend dev server proxies `/api` and
 `/static` there (a bare `flask run` uses 5000 and nothing will load):
 
@@ -161,12 +173,17 @@ tasks call `venv/` and `frontend/node_modules`).
 ## 3. The development loop
 
 1. Make a change. Backend: `flask run` auto-reloads. Frontend: Vite hot-reloads.
-2. Before committing, run the same three gates CI runs:
-   ```bash
-   bash scripts/check-naming-and-style.sh      # the LOCKED naming convention
-   venv/bin/python -m pytest tests/ -q         # backend
-   cd frontend && npx vitest run && npm run build
+2. Before committing, run the same three gates CI runs. In VS Code the
+   task **Check: naming + tests + build** runs all three; by hand:
+   ```powershell
+   bash scripts/check-naming-and-style.sh      # naming hook - needs Git Bash
+   venv\Scripts\python -m pytest tests/ -q     # backend
+   cd frontend; npx vitest run; npm run build
    ```
+   The naming check is a bash script; on Windows it runs under Git Bash
+   (installed with Git for Windows). The git PRE-COMMIT hook runs it
+   automatically on every `git commit`, so a bad name is caught even if you
+   forget to run it - just make sure Git for Windows is installed.
 3. Commit in small, working steps. Subject: short, present tense, plain
    English; body says WHY. Read `CONTRIBUTING.md` before naming anything - the
    naming hook will reject snake_case DB columns, banned shorthand, and