Document that source maps are off by default in 5.4, and how to turn them on

[kriszyp]

Documents that Harper v5.4.0 no longer enables source maps by default, and how to turn them back on. Companion to HarperFast/harper#3072, which turns them off to save several megabytes of heap per thread.

⊙ Problem

After HarperFast/harper#3072, stack traces from Harper's core point at the compiled dist/*.js files unless source maps are enabled. Nothing in the docs says source maps exist, so an operator who upgrades sees different stack traces with no explanation.

❓ Your call: the note lives in reference/configuration/debugging.md next to the inspector settings, plus a 5.4 release note. Is that where operators look for stack-trace help, or should it also appear in the logging docs?

💡 Solution

• reference/configuration/debugging.md: a new "Source Maps in Stack Traces" section (changed in v5.4.0) explaining the default, the memory reason, and NODE_OPTIONS=--enable-source-maps, which Harper passes on to every worker thread. It scopes the effect to modules Node.js loads itself: Harper's core and natively loaded application code. Harper's VM-based loaders were not mapped before either. Adds a link to Node's --enable-source-maps docs under Related.
• reference/configuration/overview.md: the See Also entry for Worker Thread Debugging mentions source maps.
• release-notes/v5-lincoln/5.4.md: a "Smaller Per-Thread Baseline" note — an idle thread's heap drops from about 58 MB to 35 MB, some dependencies load on first use, and source maps are off by default.

✅ Verification

Not observable end-to-end in this repository; prettier is clean on the changed files. The behavior described was checked against HarperFast/harper#3072 on a running server: source maps are off in the main thread and workers by default, and on in all of them with NODE_OPTIONS=--enable-source-maps or node --enable-source-maps.

_{🤖 Generated by Claude Code (Claude Opus 5.5); posted via @kriszyp.}

Related PRs: #671 independent, #709 overlaps (also adds a 5.4 release note), #712 overlaps (also adds a 5.4 release note), #710 overlaps (merged; also edits the 5.4 release notes, merges cleanly)
Complexity: easy

_{Review-Coverage: authored=claude; ran=gemini,cursor-composer,codex,cursor-muse; adjudicated=domain; declined=cursor-grok,cursor-kimi; rounds=3; full=2 @ ebb3ed4}

_{Review-Attention: skim ~2m (decisions: release-note-placement, opt-in-surface, page-home) @ ebb3ed4}

[gemini-code-assist]

Code Review

This pull request updates the documentation and release notes for Harper v5.4.0 to reflect changes in memory management and source map handling. Specifically, it documents that source maps are no longer enabled by default to reduce per-thread memory usage, and provides instructions on how to re-enable them using the NODE_OPTIONS=--enable-source-maps environment variable. It also highlights a 40% reduction in idle JavaScript heap usage due to optimized compiled code and lazy-loading of specific dependencies. No review comments were provided, so there is no additional feedback.

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-714

This preview will update automatically when you push new commits.