getting-started onboarding: docs + local-dev config + unblock backend tests (new-user review)

[tri2510]

Summary

Follows a from-scratch new-user review of docs/getting-started/, where every documented command was executed against a clean Ubuntu/Docker environment. This PR fixes the local-development issues found (docs, dev config, and unblocking the backend test suite). Product-functionality issues surfaced by the review are intentionally left untouched and listed below for follow-up.

Why

A new contributor following the docs hit blockers and inaccuracies:

• README "fastest start" ran yarn dev with no .env → backend crashed (MONGODB_URL is required).
• Self-registration returned 403 because .env.example didn't set STRICT_AUTH=false.
• yarn test failed on 5/7 suites — Jest had no ESM-transform config, so ESM-only deps couldn't be parsed.
• development-guide.md pointed at :3200 for dev access (actually :3210), a non-existent /api-docs Swagger UI, and an inconsistent Mongo container name.

Changes (local-dev only)

Docs

• README / local-dev "fastest start": explicit cp .env.example .env + note that self-registration needs STRICT_AUTH=false.
• development-guide: dev access is :3210 (Vite proxies API to :3200); :3200 unified entry is production-only; corrected the Vite proxy path list; dropped the false "backend proxies frontend in dev" claim.
• development-guide: removed the dead /api-docs Swagger reference; standardized the Mongo container name to autowrx-mongodb; aligned Node/Yarn prerequisites wording.

Backend tests

• Added @babel/core, babel-jest@29, @babel/preset-env (pinned to Babel v7 to match jest@29 + @babel/traverse@7), a babel.config.js, and whitelisted @paralleldrive/cuid2 + @noble/hashes.
• Result: 0 ESM errors; all 7 suites load and run (20/26 tests pass).

Dev config / tooling

• .env.example: add STRICT_AUTH=false (self-registration works out of the box); remove the duplicate JWT_COOKIE_NAME.
• backend/package.json: engines.node >=12 → >=18 (matches docs + the node:22 base image).
• Remove stale backend/package-lock.json + frontend/package-lock.json (yarn.lock is canonical) — eliminates the yarn "mixing lock files" warning.

Verification (clean Ubuntu/Docker env)

• cd backend && yarn test → 0 ESM errors, 7/7 suites run, 20/26 pass.
• cd backend && cp .env.example .env && yarn dev → Connected to MongoDB + Listening to port 3200 (~1s).
• POST /v2/auth/register → 201 now that .env.example ships STRICT_AUTH=false (was 403).
• cd frontend && npx tsc --noEmit && yarn build → exit 0.
• yarn install → no more "mixing lock files" warning.

Not addressed — product functionality (intentionally left for follow-up)

Per scope, no product/auth behavior was changed. These were found by the review and are noted for separate PRs:

• backend/src/models/plugins/paginate.plugin.js — docsPromise.populate(...options.populate) spreads a string into chars, causing StrictPopulateError: path 'p'. (2 failing tests.)
• backend/src/models/user.model.js — password validation only enforces minlength: 8 (no number/letter rule) and the role validator doesn't reject unknown roles; tests expect more. Needs a maintainer call on intent. (3 failing tests.)
• backend/tests/integration/docs.test.js — hits /v1/docs (the API is /v2). (1 failing test.)
• backend/src/config/config.js — MONGODB_URL has a contradictory .default(...).required(); and true zero-config boot is still blocked because JWT_SECRET has no default and passport requires it. The README's cp .env.example .env step is the practical workaround (included here).
• backend/src/scripts/convertLogsCap.js — logs a non-fatal ECONNRESET while capping the changelogs collection on every boot.
• backend/src/app.js — Swagger UI could be mounted at /api-docs (deps + @swagger annotations exist); the dead doc reference was removed instead.
• Mongo 4.4 (EOL) — instance-setup/docker-compose.prod.yml and dev-stage/docker-compose.mongodb.yml pin mongo:4.4.6-bionic. Prod-affecting upgrade to track separately.
• Husky — prepare scripts + .husky/ dirs in both packages never activate (subfolder .git not found); hooks are dead. Cleanup is a maintainer workflow decision.

Net: yarn test is 20/26 — the 6 remaining failures are all in the product/behavior items above, not in dev tooling.

Notes

• Commits are signed off (Tri Hua <tri2510@gmail.com>).