diff --git a/.gitignore b/.gitignore
index ba374815..d81657df 100644
--- a/.gitignore
+++ b/.gitignore
@@ -28,7 +28,11 @@ env/
 
 # IDE
 .idea/
-.vscode/
+.vscode/*
+# Share the team's launch/tasks/extensions; keep personal settings out.
+!.vscode/launch.json
+!.vscode/tasks.json
+!.vscode/extensions.json
 *.swp
 *.swo
 *~
diff --git a/.vscode/extensions.json b/.vscode/extensions.json
new file mode 100644
index 00000000..ef79aa0f
--- /dev/null
+++ b/.vscode/extensions.json
@@ -0,0 +1,9 @@
+{
+  "recommendations": [
+    "ms-python.python",
+    "ms-python.vscode-pylance",
+    "Vue.volar",
+    "dbaeumer.vscode-eslint",
+    "ms-azuretools.vscode-docker"
+  ]
+}
diff --git a/.vscode/launch.json b/.vscode/launch.json
new file mode 100644
index 00000000..b84a01f4
--- /dev/null
+++ b/.vscode/launch.json
@@ -0,0 +1,30 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Flask API (:5001)",
+      "type": "debugpy",
+      "request": "launch",
+      "module": "flask",
+      "cwd": "${workspaceFolder}",
+      "env": {
+        "FLASK_APP": "shopdb",
+        "FLASK_ENV": "development",
+        "FLASK_DEBUG": "1"
+      },
+      "args": ["run", "--port", "5001", "--no-reload"],
+      "jinja": true,
+      "justMyCode": false,
+      "console": "integratedTerminal"
+    },
+    {
+      "name": "Pytest (current file)",
+      "type": "debugpy",
+      "request": "launch",
+      "module": "pytest",
+      "cwd": "${workspaceFolder}",
+      "args": ["${file}", "-v"],
+      "console": "integratedTerminal"
+    }
+  ]
+}
diff --git a/.vscode/tasks.json b/.vscode/tasks.json
new file mode 100644
index 00000000..955e81fb
--- /dev/null
+++ b/.vscode/tasks.json
@@ -0,0 +1,43 @@
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "Backend: flask run (:5001)",
+      "type": "shell",
+      "command": "${workspaceFolder}/venv/bin/flask run --port 5001",
+      "options": {
+        "cwd": "${workspaceFolder}",
+        "env": { "FLASK_APP": "shopdb" }
+      },
+      "windows": {
+        "command": "${workspaceFolder}\\venv\\Scripts\\flask.exe run --port 5001"
+      },
+      "isBackground": true,
+      "problemMatcher": []
+    },
+    {
+      "label": "Frontend: npm run dev (:5173)",
+      "type": "shell",
+      "command": "npm run dev",
+      "options": { "cwd": "${workspaceFolder}/frontend" },
+      "isBackground": true,
+      "problemMatcher": []
+    },
+    {
+      "label": "Dev site (backend + frontend)",
+      "dependsOn": [
+        "Backend: flask run (:5001)",
+        "Frontend: npm run dev (:5173)"
+      ],
+      "dependsOrder": "parallel",
+      "problemMatcher": []
+    },
+    {
+      "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",
+      "options": { "cwd": "${workspaceFolder}" },
+      "problemMatcher": []
+    }
+  ]
+}
diff --git a/README.md b/README.md
index f56f740f..8296fdfc 100644
--- a/README.md
+++ b/README.md
@@ -148,11 +148,13 @@ pip install -r requirements.txt
 cp .env.example .env
 # Edit .env with your database credentials and secrets.
 
+export FLASK_APP=shopdb
 flask db upgrade
+flask plugin upgrade-all      # per-plugin schema (ADR-008)
 flask seed permissions
 flask seed settings
 flask seed reference-data
-flask run
+flask run --port 5001         # MUST be 5001 - the frontend dev server proxies here
 
 # Frontend (separate terminal)
 cd frontend
@@ -162,7 +164,10 @@ npm run build        # production build into frontend/dist (served by Flask)
 ```
 
 Complete first-run setup at `/setup`, or run `flask seed admin` for a headless
-admin account.
+admin account. The repo ships VS Code config in `.vscode/` (F5 debugs the
+backend; a "Dev site" task runs both servers). A fuller day-one walkthrough,
+including VS Code and troubleshooting, is the DEVELOPMENT-SETUP page in the
+project wiki.
 
 To import a site's legacy data, use the HTTP import surface: an admin API
 token plus the IMPORT-API page in the project wiki drive the whole migration