docs: add ONBOARDING.md engineering onboarding guide

[nollymar]

What

Adds a consolidated ONBOARDING.md at the repo root — the Engineering department's onboarding entry point, designed to be opened in Claude Code.

Closes #36113

Why

We had two partially-overlapping, stale onboarding docs (dotBackendOnboarding.md, dotFrontendOnboarding.md) pinned to old versions (Node 18, Angular 18, PrimeNG 17, Nx 19). This consolidates the still-useful content into one current guide that complements CLAUDE.md instead of duplicating it.

What's in it

• Day-one setup — sdk env install / nvm use, just commands, Docker-by-default, recommended IDEs, an enterprise proxy/network section, and the Apple Silicon / Puppeteer Chromium fix
• Codebase mental model — com.dotcms.* (modern) vs com.dotmarketing.* (legacy); backend vs frontend build worlds
• Fast testing — targeted integration tests, IDE loop, Postman, Spectator conventions (never the full suite)
• Repo landmines — BOM-only versions, auto-generated openapi.yaml, Config/Logger, REST @Schema
• Local config — admin password, feature flags, JSP/Tomcat mounting, language overrides
• First-PR flow, available Claude Code skills, and a people/comms section

Versions corrected throughout to Java 25, Node 22.15+, Angular 19+.

Intentionally excluded

• dotCMS Utilities
• License setup

Not ready for review — TODO before un-drafting

This PR is a draft. Team-specific <<PLACEHOLDER>> values still need to be filled in by the owning team:

• Enterprise proxy / registry / cert specifics + where credentials live
• Docker runtime recommendation (Apple Silicon)
• Feature-flag reference
• CI / merge-queue rules + approval expectations
• good-first-issue link
• People & comms section — Slack channels, CODEOWNERS/team map, Notion/Confluence, issue boards, release process
• Owning team + how to propose fixes
• Decide whether to delete/redirect the old dotBackendOnboarding.md / dotFrontendOnboarding.md

🤖 Generated with Claude Code

[claude]

Claude finished @nollymar's task in 1m 33s —— View job

---

Code Review — ONBOARDING.md

• Read ONBOARDING.md
• Checked against CLAUDE.md for conflicts/drift
• Verified just recipes against the actual justfile
• Review findings posted

---

Overall: The structure is solid and the intent is right. A few concrete issues to fix before merging.

---

Issues that need fixing

1. just dev-start doesn't exist (ONBOARDING.md line 72)

just dev-start-on-port 8080   # default port is 8082 if omitted; `just dev-start` picks a random port

There is no just dev-start recipe in the justfile. The parenthetical claim that it "picks a random port" is fiction — only dev-start-on-port exists, and it defaults to 8082 (not random). The comment will confuse newcomers who try just dev-start.

Fix this →

---

2. just test-postman signature is wrong (ONBOARDING.md line 177–178)

just test-postman ai          # a single collection (recommended)
just test-postman all         # all collections (slower)

The actual justfile recipe is test-postman collections='ai', which takes collections as a positional arg. Passing all would run a collection named "all", not all collections. CLAUDE.md's canonical form is:

./mvnw verify -pl :dotcms-postman -Dpostman.test.skip=false -Dpostman.collections=all

The just test-postman all shorthand claim needs verification or removal.

Fix this →

---

3. Feature-flag example uses a non-existent flag (ONBOARDING.md line 225)

DOT_FEATURE_FLAG_SEO_IMPROVEMENTS: true

DOT_FEATURE_FLAG_SEO_IMPROVEMENTS does not appear anywhere in the codebase. The real flags in dotmarketing-config.properties use the pattern FEATURE_FLAG_* (no DOT_ prefix, no _IMPROVEMENTS suffix). Using a fake flag as a concrete example teaches the wrong pattern. Either use a real flag name or make the example obviously synthetic.

Fix this →

---

Minor concerns

4. just dev-run description is inaccurate (line 75)

The guide presents just dev-run as the simple "run it locally" command and separately describes just dev-run again as "run with Glowroot profiler". These are the same command — the comment should make clear that dev-run always starts Glowroot (it's not optional). Newcomers may be surprised when Glowroot is always active.

5. just dev-stop may not be the right command (line 73)

just dev-stop exists in the justfile, but the guide pairs it with dev-start-on-port (which starts in the foreground). There's no corresponding dev-stop-port — confirm this is the right teardown command for a port-specific instance.

6. just dev-run is listed twice (lines 72–75)

just dev-start-on-port 8080   # ...
just dev-stop
just dev-run                  # run with Glowroot profiler

dev-start-on-port and dev-run serve different purposes (background vs. foreground with Glowroot) but listing them in sequence without explanation implies they're alternatives. Clarify the difference or pick one as the recommended default.

---

These do not block the draft phase, but items 1–3 should be fixed before un-drafting since they'll mislead anyone who tries to follow the guide.