docs: fix local-dev commands for PowerShell, document branching/commit conventions

README.md

@@ -15,18 +15,20 @@ frontend/ React + TypeScript + antd storefront and admin UI (Vite)
 
 ## Clone
 
-```bash
+```powershell
 git clone https://gitea.bermudalamb.synology.me/bermudalamb/redefined-designs.git
 cd redefined-designs
 ```
 
 ## Running locally
 
+Commands below are shown for **PowerShell** (Windows). A bash equivalent is noted wherever the syntax differs.
+
 ### 1. Start a local Postgres instance
 
 The backend needs Postgres to talk to during local development. `backend/docker-compose.test.yml` spins up a throwaway, tmpfs-backed instance — no data persists between restarts, which is fine for local dev and tests.
 
-```bash
+```powershell
 cd backend
 npm run db:test:up
 ```
@@ -35,12 +37,32 @@ This starts Postgres on `localhost:55432`, database `redefined_test`.
 
 ### 2. Load the schema
 
+**PowerShell:**
+```powershell
+Get-Content init.sql | docker exec -i redefined-designs-test-db psql -U redefined_test -d redefined_test
+```
+
+**bash:**
 ```bash
 docker exec -i redefined-designs-test-db psql -U redefined_test -d redefined_test < init.sql
 ```
 
 ### 3. Configure environment variables
 
+**PowerShell:**
+```powershell
+$env:PGHOST = "localhost"
+$env:PGPORT = "55432"
+$env:PGUSER = "redefined_test"
+$env:PGPASSWORD = "redefined_test"
+$env:PGDATABASE = "redefined_test"
+$env:PORT = "3000"
+$env:DEMO_MODE = "true"
+$env:UPLOADS_DIR = "$env:TEMP\redefined-uploads"
+New-Item -ItemType Directory -Force -Path $env:UPLOADS_DIR | Out-Null
+```
+
+**bash:**
 ```bash
 export PGHOST=localhost
 export PGPORT=55432
@@ -55,9 +77,11 @@ mkdir -p /tmp/redefined-uploads
 
 `DEMO_MODE=true` enables a "Buy Now (Demo)" button on the storefront that completes a purchase without needing real PayPal credentials — useful for local development and for the Playwright tests below. To exercise real PayPal checkout locally, also set `PAYPAL_CLIENT_ID`, `PAYPAL_CLIENT_SECRET`, and `PAYPAL_ENV=sandbox`.
 
+**Note (PowerShell):** environment variables set with `$env:` only last for the current terminal session/tab. If you close and reopen VS Code's terminal, you'll need to re-run step 3 before starting the backend again.
+
 ### 4. Run the backend
 
-```bash
+```powershell
 npm install
 npm run dev
 ```
@@ -66,8 +90,10 @@ Runs on `http://localhost:3000` with hot reload.
 
 ### 5. Run the frontend
 
-```bash
-cd ../frontend
+Open a **second** terminal tab/window (the backend needs to keep running in the first one):
+
+```powershell
+cd frontend
 npm install
 npm run dev
 ```
@@ -87,7 +113,7 @@ Note: locally, `/admin` is directly reachable with no login gate — the authent
 
 No database required.
 
-```bash
+```powershell
 cd backend
 npm run test:unit
 ```
@@ -96,7 +122,7 @@ npm run test:unit
 
 Exercises the real Express app against a real (disposable) Postgres instance via `supertest`.
 
-```bash
+```powershell
 cd backend
 npm run db:test:up
 npm run test:integration
@@ -107,7 +133,7 @@ npm run db:test:down   # when finished
 
 Needs the backend running against a database with the schema loaded (steps 1–4 above), since these tests drive real registration/login/purchase flows through a live API.
 
-```bash
+```powershell
 cd frontend
 npm install
 npx playwright install --with-deps   # first time only — installs browser binaries
@@ -116,8 +142,17 @@ npm run test:e2e
 
 ## CI
 
-Gitea Actions runs a SonarQube static analysis scan on every push to `main` and on pull requests — see `.gitea/workflows/sonarqube.yml`. It currently runs TypeScript build checks for both `backend` and `frontend`; wiring the Jest/Playwright suites into that same workflow is a natural next step once a CI-side Postgres service is added to the workflow definition.
+Gitea Actions runs two workflows on every push to `main` and on pull requests:
+
+- **SonarQube Analysis** (`.gitea/workflows/sonarqube.yml`) — static analysis scan, plus TypeScript build checks for both `backend` and `frontend`
+- **Tests** (`.gitea/workflows/tests.yml`) — backend unit tests, backend integration tests (against a disposable Postgres service container), and frontend Playwright e2e tests, each posting a results summary to the job's Summary tab in Gitea Actions
+
+## Branching and commits
+
+- All changes go on a branch off `main`, named `feature/<short-description>` or `fix/<short-description>` — never commit directly to `main`
+- Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/) syntax: `feat:`, `fix:`, `chore:`, `docs:`, `test:`, `ci:`, `refactor:`, etc.
+- Branches are automatically deleted after a pull request is merged
 
 ## Production deployment
 
-Production runs as a single Docker image (multi-stage build — the frontend is built to static files and served directly by the backend), deployed via Portainer behind Nginx Proxy Manager, with authentik forward-auth gating `/admin`. That infrastructure is homelab-specific and documented separately outside this repo.
+Production runs as a single Docker image (multi-stage build — the frontend is built to static files and served directly by the backend), deployed via Portainer behind Nginx Proxy Manager, with authentik forward-auth gating `/admin`. That infrastructure is homelab-specific and documented separately outside this repo.