docs: add dev setup guide and make package scripts cross-platform (Windows) (#664)

* chore: update README with environment setup instructions and demo account credentials

fix: replace rm -rf with rimraf in build scripts for cross-platform compatibility

fix: add shell option to pnpm command in db-setup script for Windows compatibility

chore: update package.json files to use rimraf instead of rm -rf for consistency

chore: add rimraf dependency to pnpm-lock.yaml

feat: add postinstall script to install lefthook git hooks in a cross-platform manner

* docs(qa): add QA test plan, flow checklists, and bug-report workflow

Add a repo-native QA execution layer on top of FEATURE_AUDIT.md (the
feature map). Test cases live in the repo; bugs live in GitHub Issues, so
there is no duplicate tracker to keep in sync.

QA system:
- FEATURE_AUDIT.md: the feature map - every feature, its user flow, and
  edge cases with file:line citations.
- qa/README.md: the workflow, severity/difficulty rubrics, label setup,
  and a static feature -> flow coverage map proving all 42 audited
  features have a test plan.
- qa/flows/01..13: per-flow happy-path checklists covering signup &
  onboarding, course authoring, people/invites/roles, student ->
  certificate, AI assistant & tutor, programs/attendance, community,
  org public site, media & import, org settings, public API/MCP,
  enterprise SSO/licensing, and billing & AI credits.
- .github/ISSUE_TEMPLATE/qa-bug.yml: a QA Bug template requiring
  severity, difficulty, area, repro steps, and a screen recording.

Dev tooling:
- package.json: add db:studio and docker:build scripts.
- packages/db: add db:studio (drizzle-kit studio); fix db:reset on
  Windows by spawning the pnpm.cmd shim with shell:true (Node's
  CVE-2024-27980 fix blocks spawning .cmd/.bat without a shell).

* chore: update QA bug template and README for clarity and improved workflow

* docs: enhance DEV_SETUP_NOTES and README for clarity on prerequisites and email setup
chore: update package.json scripts for cross-platform compatibility
feat: add cross-platform Prettier check script for pre-commit hook

* Remove QA documentation and flow files for ClassroomIO

- Deleted the entire QA README.md file which contained the QA process, bug filing guidelines, and feature coverage map.
- Removed all flow files (01 to 13) that detailed the QA testing processes for various features including admin signup, course authoring, people management, student learning, AI assistant, programs, community, org public site, media management, org settings, public API, enterprise SSO, billing, and AI credits.

* fix: update postinstall script

README.md

@@ -75,9 +75,9 @@ To get a local copy up and running, please follow these simple steps.
 
 Here is what you need to be able to run ClassroomIO.com
 
-- [Node.js](https://nodejs.org/) (Version: >=20.19.3)
-- [pnpm](https://pnpm.io/installation)
-- [Docker](https://docs.docker.com/engine/install/)
+- **[Node.js](https://nodejs.org/)** (Version: >=20.19.3) — _required_
+- **[pnpm](https://pnpm.io/installation)** (v10) — _required_; the package scripts call `pnpm` directly, so npm/yarn are not substitutes
+- **[Docker](https://docs.docker.com/engine/install/)** — _required_; runs Postgres + Redis (no local install of those needed)
 
 ### Project Structure
 
@@ -94,6 +94,11 @@ The repository also contains shared packages under `packages/` (for example `pac
 
 ### Local Setup
 
+> **Before you start:** make sure **pnpm** and **Docker** are installed (see
+> [Prerequisites](#prerequisites)). New to the project? Read
+> [`DEV_SETUP_NOTES.md`](DEV_SETUP_NOTES.md) first — it's a full step-by-step
+> walkthrough with a troubleshooting reference for the errors you're likely to hit.
+
 1. Fork the repo, then clone it:
 
    ```bash
@@ -128,22 +133,49 @@ The repository also contains shared packages under `packages/` (for example `pac
 
 5. Set up your `.env` files:
 
-   - Go to `apps/dashboard` and `apps/api`.
-   - Duplicate the `.env.example` file and rename it to `.env`
-     - Populate them with required values (at minimum):
-     - `apps/api/.env`: `DATABASE_URL`, `REDIS_URL`, `AUTH_BEARER_TOKEN`, `BETTER_AUTH_SECRET`
-     - `apps/dashboard/.env`: `PRIVATE_SERVER_URL`, `PRIVATE_SERVER_KEY`, `PUBLIC_IS_SELFHOSTED`, `DASHBOARD_ORIGIN`
-   - Optional for self-hosted Enterprise-only features (SSO, token-auth, no-tracking): set `LICENSE_KEY` in `apps/api/.env`
+   Each app reads its **own** `.env`. In `apps/api` and `apps/dashboard`, duplicate
+   `.env.example` to `.env` and fill the values below (host ports). The secret values are
+   placeholders — **generate each one** with `openssl rand -hex 32` rather than copying
+   the example text. The two `PRIVATE_SERVER_KEY` values **must match** — they
+   authenticate the dashboard's server-to-server calls to the API, so generate it once
+   and paste the same value into both files.
+
+   - `apps/api/.env`:
+
+     ```bash
+     DATABASE_URL="postgresql://postgres:postgres@localhost:5432/classroomio"
+     REDIS_URL="redis://localhost:6379"
+     PUBLIC_SERVER_URL="http://localhost:3002"
+     TRUSTED_ORIGINS="http://localhost:5173"        # the dashboard dev origin
+     BETTER_AUTH_SECRET="<generate-with-openssl-rand-hex-32>"
+     AUTH_BEARER_TOKEN="<generate-with-openssl-rand-hex-32>"
+     PRIVATE_SERVER_KEY="<generate-with-openssl-rand-hex-32>"   # generate once; use the SAME value in the dashboard
+     DASHBOARD_ORIGIN="http://localhost:5173"        # optional; used for invite/email links back to the dashboard
+     ```
+
+   - `apps/dashboard/.env`:
+
+     ```bash
+     PUBLIC_SERVER_URL="http://localhost:3002"
+     PRIVATE_SERVER_URL="http://localhost:3002"      # used by the SSR auth proxy — required, or login returns "API upstream not configured"
+     PRIVATE_SERVER_KEY="<generate-with-openssl-rand-hex-32>"   # must match the API (paste the value generated above)
+     PUBLIC_IS_SELFHOSTED=true
+     ```
+
+   - Running the background workers? Also create `apps/jobs/.env` (e.g. `cp apps/api/.env apps/jobs/.env`); it needs `REDIS_URL`. The `packages/db/.env` used by the DB scripts is set up in step 6.
+   - Optional for self-hosted Enterprise-only features (SSO, token-auth, no-tracking): set `LICENSE_KEY` in `apps/api/.env`.
 
 6. Start local infrastructure for API (Postgres + Redis) and seed the DB:
 
    ```bash
-   docker compose -f docker/docker-compose.yaml up -d postgres redis db-init
+   docker compose -f docker/docker-compose.yaml up -d postgres redis
+   cp packages/db/.env.example packages/db/.env   # one-time (Windows: Copy-Item)
+   pnpm --filter @cio/db db:setup:seed
    ```
 
    - Connect with `DATABASE_URL=postgresql://postgres:postgres@localhost:5432/classroomio`
    - Connect with `REDIS_URL=redis://localhost:6379`
-   - The `db-init` container runs migrations/seed once Postgres is healthy.
+   - `db:setup:seed` creates the schema and seeds demo data once Postgres is up. The db scripts run with their own working directory, so they read `DATABASE_URL` from `packages/db/.env` (not `apps/api/.env`).
 
 7. (Optional) Start MinIO locally for object storage (media/documents):
 
@@ -172,6 +204,8 @@ The repository also contains shared packages under `packages/` (for example `pac
    pnpm dashboard:dev
    ```
 
+   - If you see `Failed to resolve entry for package "@cio/..."`, the shared workspace packages haven't been built yet (their `dist/` is missing). Build them once with `pnpm build`, then re-run the dev commands.
+
 9. Default local URLs:
 
    - `api`: [http://localhost:3002](http://localhost:3002)