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, and links back to the two discipline-specific guides for deeper detail.

What's in it

• Day-one setup — sdk env install / nvm use, just commands, Docker-by-default, recommended IDEs, 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 (on-by-default, DOT_ prefix, FeatureFlagName.java reference), JSP/Tomcat mounting, language overrides
• First-PR flow — including how the GitHub native merge queue works (merge_group branch, required checks: tests + security + 1 approval, ~1h average to merge)
• Claude Code skills available in the repo
• People & comms — Slack channels (#eng, #eng-adrs, #be-code-review, #guild-*, #feat-*, #team-*); everything else points to the How we do Engineering doc

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

Also links to the discipline-specific dotFrontendOnboarding.md and dotBackendOnboarding.md guides.

Intentionally excluded

• dotCMS Utilities
• License setup
• Enterprise proxy / network setup (removed — not needed)

Status

All team-specific placeholders have been filled in — no <<PLACEHOLDER>> values remain. Ready for review.

Remaining follow-up (not blocking):

• Decide whether to delete/redirect the old dotBackendOnboarding.md / dotFrontendOnboarding.md

🤖 Generated with Claude Code

[claude]

Claude finished @nollymar's task in 54s —— View job

---

Rollback-Safety Analysis

• Read docs/core/ROLLBACK_UNSAFE_CATEGORIES.md
• Get full PR diff (299f341...6254f1f)
• Analyze diff against unsafe categories
• Post result (label applied)

Result: ✅ Safe to Rollback

All changes in this PR are documentation-only:

• CLAUDE.md — 1-line version bump (Angular 19+ → 21+)
• ONBOARDING.md — new file (318 lines), pure Markdown content
• dotFrontendOnboarding.md — version string updates (Angular/PrimeNG/Nx/Node)

No database migrations (runonce tasks), Elasticsearch mapping changes, contentlet_as_json version changes, API contract changes, ContentType field types, or storage-layer changes are present. N-1 can start, read data, and serve requests without any issue after this deploy.

Label AI: Safe To Rollback has been applied.

[github-actions]

🤖 Bedrock Review — qwen.qwen3-next-80b-a3b

No issues found.

---

_{Run: #28128759972 · tokens: in: 4764 · out: 14 · total: 4778}

[github-actions]

🤖 Bedrock Review — qwen.qwen3-next-80b-a3b

New Issues

• 🟡 Medium: ONBOARDING.md:288 — Suggests using export DOT_INITIAL_ADMIN_PASSWORD=admin without warning that this password is stored in shell history and may be logged in CI/CD environments; no guidance on secure secret handling (e.g., vaults, encrypted env vars). Assumption: This value is used in production-like environments. What to verify: Whether DOT_INITIAL_ADMIN_PASSWORD is ever used outside dev/local setup, and if so, whether it's being passed via insecure channels in CI.

Existing

• No prior findings to recheck.

Resolved

• No resolved items.

---

_{Run: #28129231461 · tokens: in: 4749 · out: 188 · total: 4937}

[github-actions]

🤖 Bedrock Review — qwen.qwen3-next-80b-a3b

New Issues

• 🟡 Medium: ONBOARDING.md:288 — Suggests using DOT_INITIAL_ADMIN_PASSWORD without warning about insecure storage in shell history or CI/CD environments (repeats prior finding)

Existing

• 🟡 Medium: ONBOARDING.md:288 — Suggests using DOT_INITIAL_ADMIN_PASSWORD without warning about insecure storage in shell history or CI/CD environments

Resolved

• ✅ dotFrontendOnboarding.md:7-11 — Angular/Node/Nx version updates are accurate and aligned with .nvmrc and repo requirements; no convention violation introduced.

---

_{Run: #28130244057 · tokens: in: 5139 · out: 191 · total: 5330}

[github-actions]

🤖 Bedrock Review — qwen.qwen3-next-80b-a3b

New Issues

• 🟡 Medium: ONBOARDING.md:288 — Suggests using DOT_INITIAL_ADMIN_PASSWORD without warning about insecure storage in shell history or CI/CD environments

Existing

• 🟡 Medium: ONBOARDING.md:288 — Prior finding still present (unchanged or incomplete fix)

Resolved

• ✅ CLAUDE.md:87 — Frontend Angular version update from 19+ to 21+ is intentional and aligned with dotFrontendOnboarding.md

---

_{Run: #28131029699 · tokens: in: 5358 · out: 171 · total: 5529}

[mergify]

Tick the box to add this pull request to the merge queue (same as @mergifyio queue).

• Queue this pull request

[github-actions]

🤖 dotBot Review (Bedrock)

Reviewed 3 file(s); 2 candidate(s) → 2 confirmed, 0 uncertain (unverified, kept for review).

Confirmed findings

• 🟠 High dotFrontendOnboarding.md:10 — Angular version mismatch in documentation
  The PR description specifies updating to Angular 19+, but the diff shows Angular 21.2.4 in dotFrontendOnboarding.md. This creates a discrepancy that could mislead developers about the actual Angular version required. The 3 major version difference (19 vs 21) suggests either a documentation error or versioning mistake that needs resolution.
• 🟡 Medium ONBOARDING.md:14 — Broken documentation links in ONBOARDING.md
  The grep tool found no matches for 'docs/core/ARCHITECTURE_OVERVIEW.md', 'core-web/CLAUDE.md', or 'docs/testing/API_TESTING.md' in the repository. This indicates the linked files do not exist in the current codebase, resulting in 404 errors for users following the onboarding guide. The PR adds these links but does not include the referenced files, making them invalid.

---

_{us.deepseek.r1-v1:0 · Run: #28695902040 · tokens: in: 19632 · out: 5517 · total: 25149 · calls: 6 · est. ~$0.056}

[github-actions]

🟠 [High] Angular version mismatch in documentation

The PR description specifies updating to Angular 19+, but the diff shows Angular 21.2.4 in dotFrontendOnboarding.md. This creates a discrepancy that could mislead developers about the actual Angular version required. The 3 major version difference (19 vs 21) suggests either a documentation error or versioning mistake that needs resolution.